@cs2dak/cohort 0.2.1 → 2.0.0

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");
+  });
+});

package/src/map-role-evidence.ts

@@ -0,0 +1,358 @@
+import {
+  MAP_ROLE_EVIDENCE_VERSION,
+  playerMapRoleEvidenceSchema,
+  teamMapResponsibilityEvidenceSchema,
+  type MatchMapIntelligenceFacts,
+  type PlayerMapRoleEvidence,
+  type PlayerPositionRoundFact,
+  type RoleModifier,
+  type SupportedMapName,
+  type TeamMapResponsibilityEvidence,
+  type TeamResponsibility,
+  type TeamShapeRoundFact,
+  type WeaponDuty,
+} from "@cs2dak/contract";
+import type { PlayerIdentityMap } from "./index.js";
+
+export const MAP_ROLE_MODEL_VERSION = "cs2-demo-analysis-kit/map-role-model-5.0";
+export const MAP_ROLE_THRESHOLDS = Object.freeze({
+  minimumEligibleRounds: 6,
+  reliableEligibleRounds: 12,
+  primaryAwpMinimumQualifiedRounds: 12,
+  secondaryAwpMinimumQualifiedRounds: 6,
+  dominantPositionShare: 0.45,
+  responsibilitySeparation: 0.12,
+  supportUtilityUsesPerRound: 0.4,
+  supportOpeningUtilityUsesPerRound: 0.16,
+});
+
+const SUPPORTED_MAPS = new Set<SupportedMapName>([
+  "de_ancient", "de_anubis", "de_dust2", "de_inferno", "de_mirage", "de_nuke", "de_overpass",
+]);
+
+export interface MapRoleEvidenceFacts {
+  playerPositionRounds: PlayerPositionRoundFact[];
+  teamShapeRounds: TeamShapeRoundFact[];
+}
+
+export interface MapRoleEvidenceOptions {
+  identityMap?: PlayerIdentityMap;
+  teamIdentityMap?: Record<string, string>;
+}
+
+function flatten(facts: MapRoleEvidenceFacts | MatchMapIntelligenceFacts[]): MapRoleEvidenceFacts {
+  return Array.isArray(facts)
+    ? { playerPositionRounds: facts.flatMap((fact) => fact.playerPositionRounds), teamShapeRounds: facts.flatMap((fact) => fact.teamShapeRounds) }
+    : facts;
+}
+
+export function mapRolePlayerKey(steamId64: string, map: PlayerIdentityMap): string {
+  const mapped = map[steamId64];
+  return mapped == null ? `steam:${steamId64}` : typeof mapped === "string" ? mapped : mapped.playerKey;
+}
+
+export function mapRoleTeamKey(row: { matchId: string; teamKey: string }, map: Record<string, string>): string {
+  return map[`${row.matchId}:${row.teamKey}`] ?? `${row.matchId}:${row.teamKey}`;
+}
+
+function mean(values: Array<number | null>): number | null {
+  const usable = values.filter((value): value is number => value != null && Number.isFinite(value));
+  return usable.length === 0 ? null : usable.reduce((sum, value) => sum + value, 0) / usable.length;
+}
+
+function rounded(value: number | null, digits = 3): number | null {
+  return value == null ? null : Number(value.toFixed(digits));
+}
+
+function dataQuality(rows: PlayerPositionRoundFact[]): number {
+  if (rows.length === 0) return 0;
+  const replay = rows.filter((row) => row.availability.replay === "available").length / rows.length;
+  const callouts = rows.reduce((sum, row) => sum + (row.calloutCoverage ?? 0), 0) / rows.length;
+  const economy = rows.filter((row) => row.economyType != null).length / rows.length;
+  return rounded(replay * 0.5 + callouts * 0.35 + economy * 0.15)!;
+}
+
+function evidenceStatus(rows: PlayerPositionRoundFact[], eligible: number, quality: number): "ready" | "mixed" | "insufficient" | "unknown" {
+  if (rows.length === 0 || rows.every((row) => row.availability.replay === "missing")) return "unknown";
+  if (eligible < MAP_ROLE_THRESHOLDS.minimumEligibleRounds) return "insufficient";
+  return quality < 0.72 ? "mixed" : "ready";
+}
+
+function localAwpDuty(input: { qualified: number; active: number | null; freeze: number; share: number | null; consistency: number | null }): WeaponDuty {
+  if (input.active == null) return "rifler";
+  const ownership = input.qualified > 0 ? input.freeze / input.qualified : 0;
+  if (input.qualified >= MAP_ROLE_THRESHOLDS.primaryAwpMinimumQualifiedRounds && ownership >= 0.4 && (input.share ?? 0) >= 0.55 && (input.consistency ?? 0) >= 0.55) return "primary_awper";
+  if (input.qualified >= MAP_ROLE_THRESHOLDS.secondaryAwpMinimumQualifiedRounds && ownership >= 0.18 && (input.share ?? 0) >= 0.2) return "secondary_awper";
+  if (input.freeze > 0 || input.active > 0) return "situational_awper";
+  return "rifler";
+}
+
+function locators(rows: PlayerPositionRoundFact[]): Array<{ matchId: string; roundNumber: number; positionGroupId?: string }> {
+  return [...rows]
+    .sort((a, b) => (b.openingEligibleSeconds ?? 0) - (a.openingEligibleSeconds ?? 0) || a.matchId.localeCompare(b.matchId) || a.roundNumber - b.roundNumber)
+    .slice(0, 5)
+    .map((row) => ({ matchId: row.matchId, roundNumber: row.roundNumber, positionGroupId: row.openingPositionGroupDwell[0]?.positionGroupId }));
+}
+
+interface ShapeSummary {
+  mainShare: number | null;
+  noUniqueCoreShare: number | null;
+  isolatedShare: number | null;
+  formationShares: Record<string, number>;
+}
+
+function shapeSummary(rows: PlayerPositionRoundFact[], shapeByRound: Map<string, TeamShapeRoundFact>): ShapeSummary {
+  let covered = 0;
+  let main = 0;
+  let noUniqueCore = 0;
+  let isolated = 0;
+  const formations = new Map<string, number>();
+  for (const row of rows) {
+    const shape = shapeByRound.get(`${row.matchId}\t${row.roundNumber}\t${row.teamKey}`);
+    if (!shape) continue;
+    for (const window of shape.openingWindows) {
+      const component = window.componentPlayerIndices.find((members) => members.includes(row.playerIndex));
+      if (!component) continue;
+      covered += window.coverageSeconds;
+      const largest = Math.max(...window.componentSizes);
+      const uniqueCore = largest >= 3 && window.componentSizes.filter((size) => size === largest).length === 1 && largest > window.componentSizes.reduce((sum, size) => sum + size, 0) / 2
+        ? window.componentPlayerIndices.find((members) => members.length === largest) ?? null
+        : null;
+      if (uniqueCore?.includes(row.playerIndex)) main += window.coverageSeconds;
+      if (uniqueCore == null) noUniqueCore += window.coverageSeconds;
+      if (component.length === 1) isolated += window.coverageSeconds;
+      formations.set(window.partition, (formations.get(window.partition) ?? 0) + window.coverageSeconds);
+    }
+  }
+  return {
+    mainShare: covered > 0 ? rounded(main / covered) : null,
+    noUniqueCoreShare: covered > 0 ? rounded(noUniqueCore / covered) : null,
+    isolatedShare: covered > 0 ? rounded(isolated / covered) : null,
+    formationShares: Object.fromEntries([...formations.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, rounded(value / Math.max(covered, 1))!])),
+  };
+}
+
+function responsibility(side: "t" | "ct", input: { stability: number | null; relative: number | null; openingMain: number | null; openingIsolated: number | null; delayedConvergenceShare: number | null }): TeamResponsibility {
+  const stable = input.stability ?? 0;
+  const main = input.openingMain ?? 0;
+  const isolated = input.openingIsolated ?? 0;
+  const converged = (input.delayedConvergenceShare ?? 0) > 0;
+  if (side === "t") {
+    if (isolated >= 0.28 && converged) return "late_joining";
+    if (isolated >= 0.32 && stable >= 0.45) return "extremity";
+    if (main >= 0.68) return "pack";
+    if (stable >= 0.45) return "stable_default";
+    return "mixed";
+  }
+  if (stable >= 0.6 && (input.relative ?? 0) >= 0.08 && (isolated >= 0.12 || main >= 0.35)) return "anchor_tendency";
+  if (converged && stable < 0.55) return "component_mobile";
+  if (isolated >= 0.2) return "independent_mobile";
+  if (stable >= 0.55) return "stable_position";
+  return "mixed";
+}
+
+function modifiers(input: { stability: number | null; openingIsolated: number | null; delayedConvergenceShare: number | null; utilityPerRound: number; openingUtilityPerRound: number }): RoleModifier[] {
+  const result: RoleModifier[] = [];
+  if (input.utilityPerRound >= MAP_ROLE_THRESHOLDS.supportUtilityUsesPerRound && input.openingUtilityPerRound >= MAP_ROLE_THRESHOLDS.supportOpeningUtilityUsesPerRound) result.push("utility_supportive");
+  if ((input.stability ?? 0) >= 0.55) result.push("positionally_stable");
+  if ((input.openingIsolated ?? 0) >= 0.2) result.push("spatially_isolated");
+  if ((input.delayedConvergenceShare ?? 0) > 0) result.push("component_mobile");
+  return result;
+}
+
+export function buildPlayerMapRoleEvidence(facts: MapRoleEvidenceFacts | MatchMapIntelligenceFacts[], options: MapRoleEvidenceOptions = {}): PlayerMapRoleEvidence[] {
+  const input = flatten(facts);
+  const identityMap = options.identityMap ?? {};
+  const teamIdentityMap = options.teamIdentityMap ?? {};
+  const shapeByRound = new Map(input.teamShapeRounds.map((row) => [`${row.matchId}\t${row.roundNumber}\t${row.teamKey}`, row]));
+  const groups = new Map<string, PlayerPositionRoundFact[]>();
+  for (const row of input.playerPositionRounds) {
+    if (!SUPPORTED_MAPS.has(row.mapName as SupportedMapName)) continue;
+    // Keep match granularity here. Presentation owns corpus aggregation, while scoped
+    // declarations need an exact match-time boundary rather than a mixed row.
+    const key = [mapRolePlayerKey(row.steamId64, identityMap), mapRoleTeamKey(row, teamIdentityMap), row.matchId, row.mapName, row.side].join("\t");
+    groups.set(key, [...(groups.get(key) ?? []), row]);
+  }
+
+  const cells = [...groups.entries()].map(([key, rows]) => {
+    const [playerKey, teamKey, matchId, mapName, side] = key.split("\t") as [string, string, string, SupportedMapName, "t" | "ct"];
+    const eligibleRows = rows.filter((row) => (row.openingEligibleSeconds ?? 0) > 0);
+    const eligibleSeconds = eligibleRows.reduce((sum, row) => sum + (row.openingEligibleSeconds ?? 0), 0);
+    const quality = dataQuality(rows);
+    const dwell = new Map<string, { seconds: number; rounds: Set<string> }>();
+    for (const row of eligibleRows) for (const item of row.openingPositionGroupDwell) {
+      const cell = dwell.get(item.positionGroupId) ?? { seconds: 0, rounds: new Set<string>() };
+      cell.seconds += item.seconds;
+      cell.rounds.add(`${row.matchId}:${row.roundNumber}`);
+      dwell.set(item.positionGroupId, cell);
+    }
+    const positionGroups = [...dwell.entries()].map(([positionGroupId, value]) => ({
+      positionGroupId, seconds: rounded(value.seconds, 2)!, share: eligibleSeconds > 0 ? rounded(value.seconds / eligibleSeconds)! : 0, roundCount: value.rounds.size,
+    })).sort((a, b) => b.seconds - a.seconds || a.positionGroupId.localeCompare(b.positionGroupId));
+    const dominant = positionGroups[0] ?? null;
+    const isolationSeconds = eligibleRows.reduce((sum, row) => sum + row.isolationSegments.reduce((inner, segment) => inner + segment.seconds, 0), 0);
+    const fullSeconds = eligibleRows.reduce((sum, row) => sum + (row.eligibleSeconds ?? 0), 0);
+    const shape = shapeSummary(eligibleRows, shapeByRound);
+    const qualified = eligibleRows.filter((row) => row.economyType === "full");
+    const active = qualified.some((row) => row.activeAwpSeconds != null) ? qualified.reduce((sum, row) => sum + (row.activeAwpSeconds ?? 0), 0) : null;
+    const shots = qualified.some((row) => row.awpShots != null) ? qualified.reduce((sum, row) => sum + (row.awpShots ?? 0), 0) : null;
+    const kills = qualified.some((row) => row.awpKills != null) ? qualified.reduce((sum, row) => sum + (row.awpKills ?? 0), 0) : null;
+    const byMatch = new Map<string, PlayerPositionRoundFact[]>();
+    for (const row of qualified) byMatch.set(row.matchId, [...(byMatch.get(row.matchId) ?? []), row]);
+    const matchConsistency = byMatch.size === 0 ? null : rounded([...byMatch.values()].filter((matchRows) => matchRows.some((row) => row.freezeAwpOwnership || (row.activeAwpSeconds ?? 0) >= 3)).length / byMatch.size);
+    const spatial = {
+      dominantGroupStability: dominant == null ? null : rounded(dominant.roundCount / Math.max(eligibleRows.length, 1)),
+      teamRelativeGroupShare: null as number | null,
+      isolationSeconds: fullSeconds > 0 ? rounded(isolationSeconds, 2) : null,
+      isolationShare: fullSeconds > 0 ? rounded(isolationSeconds / fullSeconds) : null,
+      rejoinCount: fullSeconds > 0 ? eligibleRows.reduce((sum, row) => sum + row.rejoinTicks.length, 0) : null,
+      delayedConvergenceRoundShare: fullSeconds > 0 ? rounded(eligibleRows.filter((row) => row.delayedConvergences.length > 0).length / Math.max(eligibleRows.length, 1)) : null,
+      movementSync: rounded(mean(eligibleRows.map((row) => row.movementSync))),
+      openingMainComponentShare: shape.mainShare,
+      openingNoUniqueCoreShare: shape.noUniqueCoreShare,
+      openingIsolatedShare: shape.isolatedShare,
+      formationShares: shape.formationShares,
+    };
+    const utilityUses = eligibleRows.reduce((sum, row) => sum + row.utilityUseCount, 0);
+    const openingUtilityUses = eligibleRows.reduce((sum, row) => sum + row.openingUtilityUseCount, 0);
+    const support = {
+      utilityUses,
+      openingUtilityUses,
+      utilityUsePerRound: rounded(utilityUses / Math.max(eligibleRows.length, 1))!,
+      openingUtilityUsePerRound: rounded(openingUtilityUses / Math.max(eligibleRows.length, 1))!,
+    };
+    return {
+      version: MAP_ROLE_EVIDENCE_VERSION, playerKey, teamKey, mapName, side,
+      status: evidenceStatus(rows, eligibleRows.length, quality),
+      confidence: rounded(Math.min(1, eligibleRows.length / MAP_ROLE_THRESHOLDS.reliableEligibleRounds) * quality)!,
+      sample: { observedRounds: rows.length, eligibleRounds: eligibleRows.length, eligibleSeconds: rounded(eligibleSeconds, 2)!, matchCount: new Set(rows.map((row) => row.matchId)).size, dataQuality: quality, coverage: rounded(mean(rows.map((row) => row.calloutCoverage))) },
+      matchIds: [matchId],
+      positionGroups, spatial, support,
+      responsibility: responsibility(side, { stability: spatial.dominantGroupStability, relative: spatial.teamRelativeGroupShare, openingMain: shape.mainShare, openingIsolated: shape.isolatedShare, delayedConvergenceShare: spatial.delayedConvergenceRoundShare }),
+      modifiers: modifiers({ stability: spatial.dominantGroupStability, openingIsolated: shape.isolatedShare, delayedConvergenceShare: spatial.delayedConvergenceRoundShare, utilityPerRound: support.utilityUsePerRound, openingUtilityPerRound: support.openingUtilityUsePerRound }),
+      awp: { duty: "rifler" as WeaponDuty, eligibleRounds: eligibleRows.length, qualifiedLongGunRounds: qualified.length, freezeOwnershipRounds: qualified.filter((row) => row.freezeAwpOwnership === true).length, activeSeconds: rounded(active, 2), shots, kills, teamActiveShare: null as number | null, usageConcentration: null as number | null, matchConsistency },
+      representativeRounds: locators(rows),
+      basis: [`${MAP_ROLE_MODEL_VERSION}：opening position/component 用于默认职责，full-round movement 用于轮转、分离和回归解释。`],
+      limitations: ["主结构职责与 utility / stability / isolation modifiers 分开；标签只描述可观察空间行为。"],
+    };
+  });
+
+  for (const cell of cells) {
+    const peers = cells.filter((peer) => peer.teamKey === cell.teamKey && peer.mapName === cell.mapName && peer.side === cell.side && peer.matchIds[0] === cell.matchIds[0]);
+    const group = cell.positionGroups[0]?.positionGroupId;
+    if (group) {
+      const values = peers.filter((peer) => peer.playerKey !== cell.playerKey).map((peer) => peer.positionGroups.find((item) => item.positionGroupId === group)?.share ?? 0);
+      cell.spatial.teamRelativeGroupShare = values.length ? rounded(cell.positionGroups[0]!.share - values.reduce((sum, value) => sum + value, 0) / values.length) : null;
+    }
+    const total = peers.reduce((sum, peer) => sum + (peer.awp.activeSeconds ?? 0), 0);
+    cell.awp.teamActiveShare = cell.awp.activeSeconds == null || total === 0 ? null : rounded(cell.awp.activeSeconds / total);
+    cell.awp.usageConcentration = total === 0 ? null : rounded(Math.max(...peers.map((peer) => peer.awp.activeSeconds ?? 0)) / total);
+    cell.awp.duty = localAwpDuty({ qualified: cell.awp.qualifiedLongGunRounds, active: cell.awp.activeSeconds, freeze: cell.awp.freezeOwnershipRounds, share: cell.awp.teamActiveShare, consistency: cell.awp.matchConsistency });
+    cell.responsibility = responsibility(cell.side, { stability: cell.spatial.dominantGroupStability, relative: cell.spatial.teamRelativeGroupShare, openingMain: cell.spatial.openingMainComponentShare, openingIsolated: cell.spatial.openingIsolatedShare, delayedConvergenceShare: cell.spatial.delayedConvergenceRoundShare });
+    cell.modifiers = modifiers({ stability: cell.spatial.dominantGroupStability, openingIsolated: cell.spatial.openingIsolatedShare, delayedConvergenceShare: cell.spatial.delayedConvergenceRoundShare, utilityPerRound: cell.support.utilityUsePerRound, openingUtilityPerRound: cell.support.openingUtilityUsePerRound });
+  }
+  return cells.map((cell) => playerMapRoleEvidenceSchema.parse(cell));
+}
+
+export function buildTeamMapResponsibilityEvidence(facts: MapRoleEvidenceFacts | MatchMapIntelligenceFacts[], options: MapRoleEvidenceOptions = {}): TeamMapResponsibilityEvidence[] {
+  const matchPlayers = buildPlayerMapRoleEvidence(facts, options);
+  const groups = new Map<string, PlayerMapRoleEvidence[]>();
+  for (const player of matchPlayers) groups.set([player.teamKey, player.mapName, player.side].join("\t"), [...(groups.get([player.teamKey, player.mapName, player.side].join("\t")) ?? []), player]);
+  return [...groups.entries()].map(([key, matchRows]) => {
+    const [teamKey, mapName, side] = key.split("\t") as [string, SupportedMapName, "t" | "ct"];
+    const byPlayer = new Map<string, PlayerMapRoleEvidence[]>();
+    for (const row of matchRows) byPlayer.set(row.playerKey, [...(byPlayer.get(row.playerKey) ?? []), row]);
+    const rows = [...byPlayer.entries()].map(([playerKey, playerRows]) => {
+      const eligibleRounds = playerRows.reduce((sum, row) => sum + row.sample.eligibleRounds, 0);
+      const eligibleSeconds = playerRows.reduce((sum, row) => sum + row.sample.eligibleSeconds, 0);
+      const weight = (pick: (row: PlayerMapRoleEvidence) => number | null, by: "rounds" | "seconds" = "seconds") => {
+        const usable = playerRows.filter((row) => pick(row) != null);
+        const denominator = usable.reduce((sum, row) => sum + (by === "rounds" ? row.sample.eligibleRounds : row.sample.eligibleSeconds), 0);
+        return denominator === 0 ? null : rounded(usable.reduce((sum, row) => sum + pick(row)! * (by === "rounds" ? row.sample.eligibleRounds : row.sample.eligibleSeconds), 0) / denominator);
+      };
+      const dwell = new Map<string, { seconds: number; rounds: number }>();
+      for (const row of playerRows) for (const group of row.positionGroups) {
+        const current = dwell.get(group.positionGroupId) ?? { seconds: 0, rounds: 0 };
+        current.seconds += group.seconds;
+        current.rounds += group.roundCount;
+        dwell.set(group.positionGroupId, current);
+      }
+      const positionGroups = [...dwell.entries()].map(([positionGroupId, value]) => ({
+        positionGroupId, seconds: rounded(value.seconds, 2)!, share: eligibleSeconds > 0 ? rounded(value.seconds / eligibleSeconds)! : 0, roundCount: value.rounds,
+      })).sort((a, b) => b.seconds - a.seconds || a.positionGroupId.localeCompare(b.positionGroupId));
+      const formations = new Set(playerRows.flatMap((row) => Object.keys(row.spatial.formationShares)));
+      const utilityUses = playerRows.reduce((sum, row) => sum + row.support.utilityUses, 0);
+      const openingUtilityUses = playerRows.reduce((sum, row) => sum + row.support.openingUtilityUses, 0);
+      const quality = weight((row) => row.sample.dataQuality) ?? 0;
+      const spatial = {
+        dominantGroupStability: positionGroups[0] == null ? null : rounded(positionGroups[0].roundCount / Math.max(eligibleRounds, 1)),
+        teamRelativeGroupShare: null as number | null,
+        isolationSeconds: playerRows.some((row) => row.spatial.isolationSeconds != null) ? rounded(playerRows.reduce((sum, row) => sum + (row.spatial.isolationSeconds ?? 0), 0), 2) : null,
+        isolationShare: weight((row) => row.spatial.isolationShare),
+        rejoinCount: playerRows.some((row) => row.spatial.rejoinCount != null) ? playerRows.reduce((sum, row) => sum + (row.spatial.rejoinCount ?? 0), 0) : null,
+        delayedConvergenceRoundShare: weight((row) => row.spatial.delayedConvergenceRoundShare, "rounds"),
+        movementSync: weight((row) => row.spatial.movementSync),
+        openingMainComponentShare: weight((row) => row.spatial.openingMainComponentShare),
+        openingNoUniqueCoreShare: weight((row) => row.spatial.openingNoUniqueCoreShare),
+        openingIsolatedShare: weight((row) => row.spatial.openingIsolatedShare),
+        formationShares: Object.fromEntries([...formations].sort().map((formation) => [formation, weight((row) => row.spatial.formationShares[formation] ?? 0) ?? 0])),
+      };
+      const support = { utilityUses, openingUtilityUses, utilityUsePerRound: rounded(utilityUses / Math.max(eligibleRounds, 1))!, openingUtilityUsePerRound: rounded(openingUtilityUses / Math.max(eligibleRounds, 1))! };
+      const active = playerRows.some((row) => row.awp.activeSeconds != null) ? rounded(playerRows.reduce((sum, row) => sum + (row.awp.activeSeconds ?? 0), 0), 2) : null;
+      const awp = {
+        duty: "rifler" as WeaponDuty,
+        eligibleRounds,
+        qualifiedLongGunRounds: playerRows.reduce((sum, row) => sum + row.awp.qualifiedLongGunRounds, 0),
+        freezeOwnershipRounds: playerRows.reduce((sum, row) => sum + row.awp.freezeOwnershipRounds, 0),
+        activeSeconds: active,
+        shots: playerRows.some((row) => row.awp.shots != null) ? playerRows.reduce((sum, row) => sum + (row.awp.shots ?? 0), 0) : null,
+        kills: playerRows.some((row) => row.awp.kills != null) ? playerRows.reduce((sum, row) => sum + (row.awp.kills ?? 0), 0) : null,
+        teamActiveShare: null as number | null,
+        usageConcentration: null as number | null,
+        matchConsistency: playerRows.length === 0 ? null : rounded(playerRows.filter((row) => row.awp.freezeOwnershipRounds > 0 || (row.awp.activeSeconds ?? 0) >= 3).length / playerRows.length),
+      };
+      const status = playerRows.every((row) => row.status === "unknown") ? "unknown" : eligibleRounds < MAP_ROLE_THRESHOLDS.minimumEligibleRounds ? "insufficient" : quality < 0.72 ? "mixed" : "ready";
+      return {
+        version: MAP_ROLE_EVIDENCE_VERSION, playerKey, teamKey, mapName, side, status,
+        confidence: rounded(Math.min(1, eligibleRounds / MAP_ROLE_THRESHOLDS.reliableEligibleRounds) * quality)!,
+        sample: { observedRounds: playerRows.reduce((sum, row) => sum + row.sample.observedRounds, 0), eligibleRounds, eligibleSeconds: rounded(eligibleSeconds, 2)!, matchCount: new Set(playerRows.flatMap((row) => row.matchIds)).size, dataQuality: quality, coverage: weight((row) => row.sample.coverage) },
+        matchIds: [...new Set(playerRows.flatMap((row) => row.matchIds))].sort(), positionGroups, spatial, support,
+        responsibility: responsibility(side, { stability: spatial.dominantGroupStability, relative: null, openingMain: spatial.openingMainComponentShare, openingIsolated: spatial.openingIsolatedShare, delayedConvergenceShare: spatial.delayedConvergenceRoundShare }),
+        modifiers: modifiers({ stability: spatial.dominantGroupStability, openingIsolated: spatial.openingIsolatedShare, delayedConvergenceShare: spatial.delayedConvergenceRoundShare, utilityPerRound: support.utilityUsePerRound, openingUtilityPerRound: support.openingUtilityUsePerRound }),
+        awp,
+        representativeRounds: playerRows.flatMap((row) => row.representativeRounds).sort((a, b) => a.matchId.localeCompare(b.matchId) || a.roundNumber - b.roundNumber).slice(0, 5),
+        basis: [`${MAP_ROLE_MODEL_VERSION}：team matrix 先聚合为唯一 player × team × map × side cell。`],
+        limitations: ["位置重叠是描述性 concentration，不自动解释为职责冲突。"],
+      } satisfies PlayerMapRoleEvidence;
+    });
+    for (const player of rows) {
+      const peers = rows.filter((peer) => peer.playerKey !== player.playerKey);
+      const group = player.positionGroups[0]?.positionGroupId;
+      if (group && peers.length) player.spatial.teamRelativeGroupShare = rounded(player.positionGroups[0]!.share - peers.reduce((sum, peer) => sum + (peer.positionGroups.find((item) => item.positionGroupId === group)?.share ?? 0), 0) / peers.length);
+      const total = rows.reduce((sum, peer) => sum + (peer.awp.activeSeconds ?? 0), 0);
+      player.awp.teamActiveShare = player.awp.activeSeconds == null || total === 0 ? null : rounded(player.awp.activeSeconds / total);
+      player.awp.usageConcentration = total === 0 ? null : rounded(Math.max(...rows.map((peer) => peer.awp.activeSeconds ?? 0)) / total);
+      player.awp.duty = localAwpDuty({ qualified: player.awp.qualifiedLongGunRounds, active: player.awp.activeSeconds, freeze: player.awp.freezeOwnershipRounds, share: player.awp.teamActiveShare, consistency: player.awp.matchConsistency });
+      player.responsibility = responsibility(side, { stability: player.spatial.dominantGroupStability, relative: player.spatial.teamRelativeGroupShare, openingMain: player.spatial.openingMainComponentShare, openingIsolated: player.spatial.openingIsolatedShare, delayedConvergenceShare: player.spatial.delayedConvergenceRoundShare });
+      player.modifiers = modifiers({ stability: player.spatial.dominantGroupStability, openingIsolated: player.spatial.openingIsolatedShare, delayedConvergenceShare: player.spatial.delayedConvergenceRoundShare, utilityPerRound: player.support.utilityUsePerRound, openingUtilityPerRound: player.support.openingUtilityUsePerRound });
+    }
+    const overlap = new Map<string, string[]>();
+    for (const player of rows) {
+      const primary = player.positionGroups[0];
+      if (primary && primary.share >= 0.35) overlap.set(primary.positionGroupId, [...(overlap.get(primary.positionGroupId) ?? []), player.playerKey]);
+    }
+    const positionOverlap = [...overlap.entries()].filter(([, keys]) => keys.length >= 2).map(([positionGroupId, playerKeys]) => ({ positionGroupId, playerKeys: [...new Set(playerKeys)].sort(), share: rounded(new Set(playerKeys).size / Math.max(rows.length, 1))! })).sort((a, b) => a.positionGroupId.localeCompare(b.positionGroupId));
+    const positionConcentration = overlap.size === 0 ? null : rounded(Math.max(...[...overlap.values()].map((keys) => new Set(keys).size)) / Math.max(rows.length, 1));
+    const usable = rows.filter((row) => row.status === "ready" || row.status === "mixed");
+    const unstableCoverage = usable.length > 0 && (usable.some((row) => (row.spatial.dominantGroupStability ?? 1) < 0.45) || usable.filter((row) => row.status === "mixed").length / usable.length >= 0.5);
+    const status = usable.length === 0 ? rows.some((row) => row.status === "unknown") ? "unknown" : "insufficient" : usable.length < 2 ? "insufficient" : unstableCoverage ? "mixed" : "ready";
+    return teamMapResponsibilityEvidenceSchema.parse({
+      version: MAP_ROLE_EVIDENCE_VERSION, teamKey, mapName, side, status,
+      confidence: rounded(rows.reduce((sum, row) => sum + row.confidence * row.sample.eligibleSeconds, 0) / Math.max(rows.reduce((sum, row) => sum + row.sample.eligibleSeconds, 0), 1))!,
+      players: rows.map((row) => playerMapRoleEvidenceSchema.parse(row)).sort((a, b) => a.playerKey.localeCompare(b.playerKey)), positionOverlap, positionConcentration, unstableCoverage,
+      representativeRounds: rows.flatMap((row) => row.representativeRounds).slice(0, 5),
+      basis: ["逐回合 opening component membership、position group 与 full-round continuity 共同形成描述性职责。"],
+      limitations: ["不强制五个位置或职责覆盖；position overlap / concentration 只描述多人常驻同组。"],
+    });
+  }).sort((a, b) => a.teamKey.localeCompare(b.teamKey) || a.mapName.localeCompare(b.mapName) || a.side.localeCompare(b.side));
+}

package/src/patterns.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+import type { DemoPackage } from "@cs2dak/contract";
+import { buildOpeningPatternClusters } from "./patterns.js";
+
+function pkg(overrides?: Partial<DemoPackage>): DemoPackage {
+  return {
+    manifest: {
+      schemaVersion: "cs2-demo-format/3.0",
+      exporter: { name: "test", version: "0" },
+      parser: { name: "test", version: "0" },
+      demo: { hash: null, sourceFileName: null },
+      mapName: "de_mirage",
+      tickrate: 64,
+      exportedAt: "2026-01-01T00:00:00Z",
+      files: {
+        match: "match.json",
+        players: "players.json",
+        rounds: "rounds.json",
+        playerStats: "player-stats.json",
+        playerEconomies: "player-economies.json",
+        kills: "kills.json",
+        damages: "damages.json",
+        blinds: "blinds.json",
+        bombs: "bombs.json",
+        grenades: "grenades.json",
+        clutches: "clutches.json"
+      }
+    },
+    match: {
+      mapName: "de_mirage",
+      tickrate: 64,
+      durationSeconds: 120,
+      serverName: null,
+      source: "test",
+      teamA: { teamKey: "teamA", name: "A", score: 1 },
+      teamB: { teamKey: "teamB", name: "B", score: 0 }
+    },
+    players: [
+      { steamId64: "76561198000000001", name: "A", teamKey: "teamA" },
+      { steamId64: "76561198000000002", name: "B", teamKey: "teamB" }
+    ],
+    rounds: [{
+      roundNumber: 1,
+      startTick: 1,
+      freezeEndTick: 64,
+      endTick: 4096,
+      teamASide: "t",
+      teamBSide: "ct",
+      teamAScoreBefore: 0,
+      teamBScoreBefore: 0,
+      teamAEconomy: "full",
+      teamBEconomy: "full",
+      winnerTeamKey: "teamA",
+      winnerSide: "t",
+      endReason: "t_win"
+    }],
+    playerEconomies: [],
+    playerStats: [],
+    kills: [],
+    damages: [],
+    blinds: [],
+    bombs: [],
+    grenades: [],
+    clutches: [],
+    ...overrides
+  } as DemoPackage;
+}
+
+describe("buildOpeningPatternClusters", () => {
+  it("clusters rounds by replay callout distribution and grenade sequence", () => {
+    const places = Array.from({ length: 16 }, () => 0);
+    const demo = pkg({
+      replay: {
+        meta: { tickrate: 64, sampleRate: 1, coordScale: 1, angleScale: 10 },
+        placeDict: ["TSpawn", "LongDoors"],
+        weaponDict: [],
+        rounds: [{
+          roundNumber: 1,
+          startTick: 64,
+          tickStep: 64,
+          frameCount: 16,
+          projectiles: [],
+          players: [
+            {
+              playerIndex: 0,
+              x: [0], y: [0], z: [0], yaw: [0], pitch: [0],
+              hp: Array.from({ length: 16 }, () => 100),
+              armor: Array.from({ length: 16 }, () => 100),
+              money: Array.from({ length: 16 }, () => 800),
+              equipValue: Array.from({ length: 16 }, () => 800),
+              place: places,
+              flash: Array.from({ length: 16 }, () => 0),
+              flags: Array.from({ length: 16 }, () => 1),
+              weapon: Array.from({ length: 16 }, () => -1),
+              grenades: Array.from({ length: 16 }, () => [])
+            },
+            {
+              playerIndex: 1,
+              x: [0], y: [0], z: [0], yaw: [0], pitch: [0],
+              hp: Array.from({ length: 16 }, () => 100),
+              armor: Array.from({ length: 16 }, () => 100),
+              money: Array.from({ length: 16 }, () => 800),
+              equipValue: Array.from({ length: 16 }, () => 800),
+              place: Array.from({ length: 16 }, () => 1),
+              flash: Array.from({ length: 16 }, () => 0),
+              flags: Array.from({ length: 16 }, () => 1),
+              weapon: Array.from({ length: 16 }, () => -1),
+              grenades: Array.from({ length: 16 }, () => [])
+            }
+          ]
+        }]
+      },
+      grenades: [
+        {
+          roundNumber: 1, grenadeId: null,
+          throwTick: 70, effectTick: 80, destroyTick: null,
+          grenade: "smoke",
+          throwerIndex: 0, throwPosition: { x: 0, y: 0, z: 0 },
+          effectPosition: { x: 0, y: 0, z: 0 }
+        }
+      ]
+    });
+    const clusters = buildOpeningPatternClusters([{ matchId: "m1", pkg: demo }], { windowSeconds: 15 });
+    expect(clusters).toHaveLength(2);
+    const tCluster = clusters.find((cluster) => cluster.side === "t");
+    expect(tCluster?.basis).toBe("TSpawn:1");
+    expect(tCluster?.grenadeSequence).toEqual(["smoke"]);
+    expect(tCluster?.roundCount).toBe(1);
+  });
+
+  it("returns empty when no grenade or position data defines the opening", () => {
+    const demo = pkg();
+    const clusters = buildOpeningPatternClusters([{ matchId: "m1", pkg: demo }]);
+    expect(clusters).toEqual([]);
+  });
+});