@cs2dak/cohort 1.0.0 → 2.0.0

package/src/t-role-research-projection.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import type { PlayerPositionRoundFact, TResponsibilityResearchFeatures, TeamShapeRoundFact } from "@cs2dak/contract";
+import { buildPlayerMapRoleEvidence } from "./map-role-evidence.js";
+import { buildTResponsibilityResearchProjections, scoreFrozenTResponsibilityFeatures } from "./t-role-research-projection.js";
+
+const LUCHOV_FEATURES: TResponsibilityResearchFeatures = {
+  dominantGroupStability: 0.8125875,
+  teamRelativeGroupShare: 0.1741208333,
+  openingIsolatedShare: 0.275425,
+  isolationShare: 0.3739791667,
+  delayedConvergenceShare: 0.1209125,
+  movementSync: 0.3243583333,
+  positionTopShare: 0.4567125,
+  openingLargestShare: 0.7837100236,
+  fullLargestShare: 0.784060982,
+  meanTeamCentroidDistance: 683.9742873697,
+  openingPathDisplacement: 1926.1863987284,
+  openingPathTransitions: 0.3837471185,
+  openingPositionEntropy: 0.8382271237,
+  fullPositionEntropy: 0.8975500986,
+  rejoinsPerMinute: 5.2426204323,
+};
+
+function row(playerIndex: number, roundNumber: number, overrides: Partial<PlayerPositionRoundFact> = {}): PlayerPositionRoundFact {
+  return {
+    analysisVersion: 6,
+    matchId: "m1",
+    mapName: "de_ancient",
+    roundNumber,
+    teamKey: "teamA",
+    side: "t",
+    playerIndex,
+    steamId64: `7656119800000000${playerIndex + 1}`,
+    economyType: "full",
+    openingWindow: { version: 1, startTick: 100, endTick: 1380, configuredSeconds: 20 },
+    openingEligibleSeconds: 20,
+    openingPositionGroupDwell: [{ positionGroupId: playerIndex === 0 ? "a_default" : "mid_default", seconds: 20, share: 1 }],
+    openingMeanComponentSize: 2,
+    openingIsolationSeconds: 0,
+    openingUtilityUseCount: 0,
+    openingPath: [
+      { tick: 100, callout: "Start", positionGroupId: "spawn", x: 0, y: 0, z: 0 },
+      { tick: 1380, callout: "A", positionGroupId: "a_default", x: 1000, y: 0, z: 0 },
+    ],
+    eligibleSeconds: 40,
+    positionGroupDwell: [{ positionGroupId: playerIndex === 0 ? "a_default" : "mid_default", seconds: 40, share: 1 }],
+    unresolvedCalloutSeconds: 0,
+    calloutCoverage: 1,
+    meanNearestTeammateDistance: 250,
+    meanTeamCentroidDistance: 500,
+    meanComponentSize: 2,
+    isolationSegments: [],
+    rejoinTicks: [],
+    delayedConvergences: [],
+    movementSync: 0.3,
+    utilityUseCount: 0,
+    freezeAwpOwnership: false,
+    activeAwpSeconds: 0,
+    awpShots: 0,
+    awpKills: 0,
+    availability: { replay: "available", nav: "available", callouts: "available", shots: "available" },
+    ...overrides,
+  };
+}
+
+function shape(roundNumber: number): TeamShapeRoundFact {
+  const window = {
+    startTick: 100,
+    endTick: 1380,
+    coverageSeconds: 20,
+    componentSizes: [2, 2, 1],
+    partition: "2+2+1",
+    componentPlayerIndices: [[0, 1], [2, 3], [4]],
+  };
+  return {
+    analysisVersion: 6,
+    matchId: "m1",
+    mapName: "de_ancient",
+    roundNumber,
+    teamKey: "teamA",
+    side: "t",
+    openingWindow: { version: 1, startTick: 100, endTick: 1380, configuredSeconds: 20 },
+    openingWindows: [window],
+    coverageSeconds: 20,
+    windows: [window],
+    availability: { replay: "available", nav: "available", callouts: "available", shots: "available" },
+  };
+}
+
+describe("T responsibility research projection", () => {
+  it("reproduces the frozen full-fit score for a committed feature vector", () => {
+    expect(scoreFrozenTResponsibilityFeatures(LUCHOV_FEATURES)).toEqual({
+      packScore: 0.750651,
+      lurkerScore: 0.249349,
+      confidence: 0.750651,
+      candidate: "pack",
+    });
+  });
+
+  it("credits tied two-player action units without redefining them as a unique core", () => {
+    const rows = Array.from({ length: 12 }, (_, index) => [row(0, index + 1), row(1, index + 1)]).flat();
+    const shapes = Array.from({ length: 12 }, (_, index) => shape(index + 1));
+    const oldEvidence = buildPlayerMapRoleEvidence({ playerPositionRounds: rows, teamShapeRounds: shapes });
+    expect(oldEvidence[0]?.spatial.openingMainComponentShare).toBe(0);
+
+    const projection = buildTResponsibilityResearchProjections({ playerPositionRounds: rows, teamShapeRounds: shapes });
+    expect(projection).toHaveLength(2);
+    expect(projection[0]?.features).toMatchObject({ openingLargestShare: 1, fullLargestShare: 1 });
+    expect(projection[0]?.candidate).not.toBeNull();
+    expect(projection[0]?.basis[0]).toContain("正式 responsibility 保持不变");
+  });
+
+  it("preserves research feature precision until final score serialization", () => {
+    const rows = Array.from({ length: 12 }, (_, index) => row(0, index + 1, {
+      meanTeamCentroidDistance: index % 2 === 0 ? 500.1234567891234 : 500.9876543219876,
+    }));
+
+    const projection = buildTResponsibilityResearchProjections({ playerPositionRounds: rows, teamShapeRounds: [] })[0]!;
+    expect(projection.features.meanTeamCentroidDistance).toBeCloseTo(500.5555555555555, 11);
+    expect(projection.features.meanTeamCentroidDistance).not.toBe(500.555556);
+    expect(projection.packScore?.toString().split(".")[1]?.length ?? 0).toBeLessThanOrEqual(6);
+  });
+
+  it("keeps missing replay and unobserved features unknown instead of imputing a role", () => {
+    const missing = row(0, 1, {
+      openingWindow: null,
+      openingEligibleSeconds: null,
+      openingPositionGroupDwell: [],
+      openingPath: [],
+      eligibleSeconds: null,
+      positionGroupDwell: [],
+      calloutCoverage: null,
+      meanTeamCentroidDistance: null,
+      movementSync: null,
+      availability: { replay: "missing", nav: "missing", callouts: "missing", shots: "missing" },
+    });
+    expect(buildTResponsibilityResearchProjections({ playerPositionRounds: [missing], teamShapeRounds: [] })[0]).toMatchObject({
+      status: "unknown",
+      candidate: null,
+      packScore: null,
+      lurkerScore: null,
+    });
+  });
+});

package/src/t-role-research-projection.ts

@@ -0,0 +1,241 @@
+import {
+  T_RESPONSIBILITY_RESEARCH_PROJECTION_VERSION,
+  tResponsibilityResearchProjectionSchema,
+  type MatchMapIntelligenceFacts,
+  type PlayerMapRoleEvidence,
+  type PlayerPositionRoundFact,
+  type TResponsibilityResearchFeatures,
+  type TResponsibilityResearchProjection,
+  type TeamShapeRoundFact,
+} from "@cs2dak/contract";
+import {
+  MAP_ROLE_THRESHOLDS,
+  buildPlayerMapRoleEvidence,
+  mapRolePlayerKey,
+  mapRoleTeamKey,
+  type MapRoleEvidenceFacts,
+  type MapRoleEvidenceOptions,
+} from "./map-role-evidence.js";
+
+export const T_RESPONSIBILITY_RESEARCH_MODEL_ID = "cologne-major-2026/parsimonious-v1-full-fit" as const;
+export const T_RESPONSIBILITY_RESEARCH_THRESHOLD = 0.6;
+
+type FeatureKey = keyof TResponsibilityResearchFeatures;
+
+/**
+ * Full-fit parameters frozen from the 159-identity Cologne research population.
+ * This same-event diagnostic is intentionally not used by the production role selector.
+ */
+const FROZEN_MODEL: ReadonlyArray<readonly [FeatureKey, number, number, number, number]> = [
+  ["dominantGroupStability", 0.8125875, 0.8110319885369233, 0.06571674270323856, 0.3137454154793391],
+  ["teamRelativeGroupShare", 0.1838809523809523, 0.1917499578233378, 0.08708704820909378, -0.8074881283271113],
+  ["openingIsolatedShare", 0.3238657718120805, 0.32872615302182945, 0.07824780489800287, -0.4081235105208964],
+  ["isolationShare", 0.4547809523809524, 0.46189704535089304, 0.07746145337427911, -0.20892974673701006],
+  ["delayedConvergenceShare", 0.1265747126436781, 0.12579053416940641, 0.04034628766284785, 0.15699043839244245],
+  ["movementSync", 0.2942472527472527, 0.2927666973414002, 0.03747820111822078, 0.08503051685027664],
+  ["positionTopShare", 0.4328125, 0.43450227509018796, 0.056193812672360524, 0.006865937081921921],
+  ["openingLargestShare", 0.7196198234894773, 0.7102014308840938, 0.08058945177379023, 0.3572344571519129],
+  ["fullLargestShare", 0.730539172627264, 0.7202883174049193, 0.06744299727584371, 0.03235009840115323],
+  ["meanTeamCentroidDistance", 793.5978242656994, 810.2038869113109, 114.10938623158178, -0.018770230983947287],
+  ["openingPathDisplacement", 1926.1863987283657, 1924.3626053132587, 166.35401831829978, -0.725988428680296],
+  ["openingPathTransitions", 0.5263157894736842, 0.5342869975778368, 0.14190394001266585, 0.012016769453277712],
+  ["openingPositionEntropy", 0.8362989193520769, 0.8291977740731681, 0.049059785225589556, 0.3891136867077831],
+  ["fullPositionEntropy", 0.8641613487733687, 0.8540405403082293, 0.05413800821242758, -0.08031875309551142],
+  ["rejoinsPerMinute", 5.111140689471583, 5.155634195709956, 0.6648081842049797, 0.45060956741302444],
+];
+const FROZEN_INTERCEPT = -0.061863082589897124;
+
+function rounded(value: number | null, digits = 6): number | null {
+  return value == null ? null : Number(value.toFixed(digits));
+}
+
+function researchFeature(value: number | null): number | null {
+  return rounded(value, 12);
+}
+
+function weighted<T>(rows: readonly T[], value: (row: T) => number | null, weight: (row: T) => number): number | null {
+  const usable = rows.flatMap((row) => {
+    const candidate = value(row);
+    const rowWeight = weight(row);
+    return candidate != null && Number.isFinite(candidate) && rowWeight > 0 ? [{ value: candidate, weight: rowWeight }] : [];
+  });
+  const total = usable.reduce((sum, row) => sum + row.weight, 0);
+  return total === 0 ? null : usable.reduce((sum, row) => sum + row.value * row.weight, 0) / total;
+}
+
+function entropy(seconds: ReadonlyMap<string, number>): number | null {
+  const values = [...seconds.values()].filter((value) => value > 0);
+  if (values.length === 0) return null;
+  if (values.length === 1) return 0;
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return -values.reduce((sum, value) => {
+    const probability = value / total;
+    return sum + probability * Math.log(probability);
+  }, 0) / Math.log(values.length);
+}
+
+interface ComponentTotals {
+  covered: number;
+  largest: number;
+}
+
+function addComponentWindows(
+  target: ComponentTotals,
+  windows: TeamShapeRoundFact["windows"],
+  playerIndex: number,
+): void {
+  for (const window of windows) {
+    const component = window.componentPlayerIndices.find((members) => members.includes(playerIndex));
+    if (!component || window.coverageSeconds <= 0) continue;
+    const largest = Math.max(...window.componentPlayerIndices.map((members) => members.length));
+    target.covered += window.coverageSeconds;
+    if (component.length === largest) target.largest += window.coverageSeconds;
+  }
+}
+
+function pathMetrics(row: PlayerPositionRoundFact): { displacement: number | null; transitions: number | null } {
+  if (row.openingPath.length < 2) return { displacement: null, transitions: null };
+  const first = row.openingPath[0]!;
+  const last = row.openingPath.at(-1)!;
+  const groups = row.openingPath.flatMap((point) => point.positionGroupId == null ? [] : [point.positionGroupId]);
+  return {
+    displacement: Math.hypot(last.x - first.x, last.y - first.y, last.z - first.z),
+    transitions: groups.slice(1).reduce((sum, group, index) => sum + Number(group !== groups[index]), 0),
+  };
+}
+
+export function scoreFrozenTResponsibilityFeatures(features: TResponsibilityResearchFeatures): {
+  packScore: number;
+  lurkerScore: number;
+  confidence: number;
+  candidate: "pack" | "lurker" | "flexible";
+} {
+  let logit = FROZEN_INTERCEPT;
+  for (const [key, median, mean, scale, coefficient] of FROZEN_MODEL) {
+    const value = features[key] ?? median;
+    logit += coefficient * ((value - mean) / scale);
+  }
+  const packScore = 1 / (1 + Math.exp(-logit));
+  const lurkerScore = 1 - packScore;
+  const confidence = Math.max(packScore, lurkerScore);
+  return {
+    packScore: rounded(packScore)!,
+    lurkerScore: rounded(lurkerScore)!,
+    confidence: rounded(confidence)!,
+    candidate: confidence < T_RESPONSIBILITY_RESEARCH_THRESHOLD ? "flexible" : packScore >= lurkerScore ? "pack" : "lurker",
+  };
+}
+
+function flatten(facts: MapRoleEvidenceFacts | MatchMapIntelligenceFacts[]): MapRoleEvidenceFacts {
+  return Array.isArray(facts)
+    ? {
+        playerPositionRounds: facts.flatMap((fact) => fact.playerPositionRounds),
+        teamShapeRounds: facts.flatMap((fact) => fact.teamShapeRounds),
+      }
+    : facts;
+}
+
+function projectionStatus(evidence: readonly PlayerMapRoleEvidence[], rounds: readonly PlayerPositionRoundFact[]): "ready" | "mixed" | "insufficient" | "unknown" {
+  if (rounds.length === 0 || rounds.every((row) => row.availability.replay === "missing")) return "unknown";
+  const eligible = evidence.reduce((sum, row) => sum + row.sample.eligibleRounds, 0);
+  if (eligible < MAP_ROLE_THRESHOLDS.reliableEligibleRounds) return "insufficient";
+  const quality = weighted(evidence, (row) => row.sample.dataQuality, (row) => row.sample.eligibleRounds);
+  return (quality ?? 0) < 0.72 ? "mixed" : "ready";
+}
+
+/** Builds an event/corpus-level T projection without changing formal role evidence. */
+export function buildTResponsibilityResearchProjections(
+  facts: MapRoleEvidenceFacts | MatchMapIntelligenceFacts[],
+  options: MapRoleEvidenceOptions = {},
+): TResponsibilityResearchProjection[] {
+  const input = flatten(facts);
+  const identityMap = options.identityMap ?? {};
+  const teamIdentityMap = options.teamIdentityMap ?? {};
+  const evidence = buildPlayerMapRoleEvidence(input, options).filter((row) => row.side === "t");
+  const evidenceGroups = new Map<string, PlayerMapRoleEvidence[]>();
+  for (const row of evidence) {
+    const key = `${row.playerKey}\t${row.teamKey}`;
+    evidenceGroups.set(key, [...(evidenceGroups.get(key) ?? []), row]);
+  }
+  const roundGroups = new Map<string, PlayerPositionRoundFact[]>();
+  for (const row of input.playerPositionRounds) {
+    if (row.side !== "t") continue;
+    const key = `${mapRolePlayerKey(row.steamId64, identityMap)}\t${mapRoleTeamKey(row, teamIdentityMap)}`;
+    roundGroups.set(key, [...(roundGroups.get(key) ?? []), row]);
+  }
+  const shapeByRound = new Map(input.teamShapeRounds.map((row) => [`${row.matchId}\t${row.roundNumber}\t${row.teamKey}\t${row.side}`, row]));
+
+  return [...evidenceGroups.entries()].map(([key, evidenceRows]) => {
+    const [playerKey, teamKey] = key.split("\t") as [string, string];
+    const rounds = roundGroups.get(key) ?? [];
+    const openingComponents: ComponentTotals = { covered: 0, largest: 0 };
+    const fullComponents: ComponentTotals = { covered: 0, largest: 0 };
+    const openingDwell = new Map<string, number>();
+    const fullDwell = new Map<string, number>();
+    const paths = rounds.map((row) => ({ row, ...pathMetrics(row) }));
+    for (const row of rounds) {
+      const shape = shapeByRound.get(`${row.matchId}\t${row.roundNumber}\t${row.teamKey}\t${row.side}`);
+      if (shape) {
+        addComponentWindows(openingComponents, shape.openingWindows, row.playerIndex);
+        addComponentWindows(fullComponents, shape.windows, row.playerIndex);
+      }
+      for (const dwell of row.openingPositionGroupDwell) {
+        const dwellKey = `${row.mapName}:${dwell.positionGroupId}`;
+        openingDwell.set(dwellKey, (openingDwell.get(dwellKey) ?? 0) + dwell.seconds);
+      }
+      for (const dwell of row.positionGroupDwell) {
+        const dwellKey = `${row.mapName}:${dwell.positionGroupId}`;
+        fullDwell.set(dwellKey, (fullDwell.get(dwellKey) ?? 0) + dwell.seconds);
+      }
+    }
+    const totalEligibleSeconds = rounds.reduce((sum, row) => sum + (row.eligibleSeconds ?? 0), 0);
+    const features: TResponsibilityResearchFeatures = {
+      dominantGroupStability: researchFeature(weighted(evidenceRows, (row) => row.spatial.dominantGroupStability, (row) => row.sample.eligibleRounds)),
+      teamRelativeGroupShare: researchFeature(weighted(evidenceRows, (row) => row.spatial.teamRelativeGroupShare, (row) => row.sample.eligibleRounds)),
+      openingIsolatedShare: researchFeature(weighted(evidenceRows, (row) => row.spatial.openingIsolatedShare, (row) => row.sample.eligibleRounds)),
+      isolationShare: researchFeature(weighted(evidenceRows, (row) => row.spatial.isolationShare, (row) => row.sample.eligibleRounds)),
+      delayedConvergenceShare: researchFeature(weighted(evidenceRows, (row) => row.spatial.delayedConvergenceRoundShare, (row) => row.sample.eligibleRounds)),
+      movementSync: researchFeature(weighted(evidenceRows, (row) => row.spatial.movementSync, (row) => row.sample.eligibleRounds)),
+      positionTopShare: researchFeature(weighted(evidenceRows, (row) => row.positionGroups[0]?.share ?? null, (row) => row.sample.eligibleRounds)),
+      openingLargestShare: openingComponents.covered === 0 ? null : researchFeature(openingComponents.largest / openingComponents.covered),
+      fullLargestShare: fullComponents.covered === 0 ? null : researchFeature(fullComponents.largest / fullComponents.covered),
+      meanTeamCentroidDistance: researchFeature(weighted(rounds, (row) => row.meanTeamCentroidDistance, (row) => row.eligibleSeconds ?? 0)),
+      openingPathDisplacement: researchFeature(weighted(paths, (row) => row.displacement, (row) => row.row.openingEligibleSeconds ?? 0)),
+      openingPathTransitions: researchFeature(weighted(paths, (row) => row.transitions, (row) => row.row.openingEligibleSeconds ?? 0)),
+      openingPositionEntropy: researchFeature(entropy(openingDwell)),
+      fullPositionEntropy: researchFeature(entropy(fullDwell)),
+      rejoinsPerMinute: totalEligibleSeconds === 0 ? null : researchFeature(60 * rounds.reduce((sum, row) => sum + row.rejoinTicks.length, 0) / totalEligibleSeconds),
+    };
+    const status = projectionStatus(evidenceRows, rounds);
+    const score = status === "unknown" || status === "insufficient" ? null : scoreFrozenTResponsibilityFeatures(features);
+    return tResponsibilityResearchProjectionSchema.parse({
+      version: T_RESPONSIBILITY_RESEARCH_PROJECTION_VERSION,
+      modelId: T_RESPONSIBILITY_RESEARCH_MODEL_ID,
+      playerKey,
+      teamKey,
+      side: "t",
+      status,
+      candidate: score?.candidate ?? null,
+      packScore: score?.packScore ?? null,
+      lurkerScore: score?.lurkerScore ?? null,
+      confidence: score?.confidence ?? null,
+      sample: {
+        observedRounds: rounds.length,
+        eligibleRounds: evidenceRows.reduce((sum, row) => sum + row.sample.eligibleRounds, 0),
+        eligibleSeconds: rounded(totalEligibleSeconds, 3)!,
+        matchCount: new Set(rounds.map((row) => row.matchId)).size,
+        mapCount: new Set(rounds.map((row) => row.mapName)).size,
+        dataQuality: rounded(weighted(evidenceRows, (row) => row.sample.dataQuality, (row) => row.sample.eligibleRounds)),
+      },
+      features,
+      matchIds: [...new Set(rounds.map((row) => row.matchId))].sort(),
+      representativeRounds: evidenceRows.flatMap((row) => row.representativeRounds).sort((a, b) => a.matchId.localeCompare(b.matchId) || a.roundNumber - b.roundNumber).slice(0, 8),
+      basis: ["科隆 Major 冻结 15 特征同赛事 full-fit 诊断投影；正式 responsibility 保持不变。"],
+      limitations: [
+        "尚无新赛事外部验证；packScore / lurkerScore 不是校准概率。",
+        "主狙职责必须由调用方依据独立 weapon duty 处理。",
+        "Flexible 表示默认 0.60 confidence threshold 下 abstain，不是拟合的第三类。",
+      ],
+    });
+  }).sort((a, b) => a.teamKey.localeCompare(b.teamKey) || a.playerKey.localeCompare(b.playerKey));
+}

package/src/tactical-clusters.ts

@@ -0,0 +1,223 @@
+import type { OpeningPattern } from "@cs2dak/core";
+
+export type TacticalExecuteBucket = "rush" | "fast" | "mid" | "late";
+export type EconomyEntry = "pistol" | "gun" | "anti_eco" | "force" | "semi" | "eco";
+
+export interface TacticalPatternRow {
+  side: "t" | "ct";
+  targetSite: "a" | "b" | null;
+  matchId: string;
+  mapName: string;
+  teamKey: string;
+  /** 调用方可提供跨场 canonical identity；缺省时兼容回退到规范化原始名称。 */
+  teamIdentity?: string;
+  opponentIdentity?: string;
+  teamName: string;
+  opponentName: string;
+  economy: string;
+  opponentEconomy: string;
+  won: boolean;
+  roundNumber: number;
+  openingPattern: OpeningPattern;
+  siteEntries: {
+    a: { entrants: number; order: Array<{ entryCallout: string | null; entryChokeId?: string | null; routeFamilyId?: string | null }> };
+    b: { entrants: number; order: Array<{ entryCallout: string | null; entryChokeId?: string | null; routeFamilyId?: string | null }> };
+  };
+  plant: unknown | null;
+  grenades: Array<{ type: string; targetRegion: "a" | "b" | "mid" | "other" | "unknown" }>;
+  c4Route: { endRegion: "a" | "b" | "mid" | "other" | null; rotated: boolean } | null;
+  executeBucket: TacticalExecuteBucket | null;
+}
+
+export interface TacticalEntryEvidenceRoute {
+  site: "a" | "b";
+  combo: string;
+  roundCount: number;
+  percentOfCovered: number;
+}
+
+export interface TacticalEntryEvidence {
+  coveredRounds: number;
+  totalRounds: number;
+  coveragePercent: number;
+  routes: TacticalEntryEvidenceRoute[];
+}
+
+export interface TacticalCluster {
+  id: string;
+  mapName: string;
+  side: TacticalPatternRow["side"];
+  economyEntry: EconomyEntry;
+  /** 当前事实中可用的跨场队伍身份（规范化 teamName）。 */
+  teamIdentity: string;
+  teamName: string;
+  opponentNames: string[];
+  opponentIdentities: string[];
+  /** 真实 OpeningPattern 的区域人数与 spread，不含任何最终打点事实。 */
+  openingIntent: Pick<OpeningPattern, "regionCounts" | "spread">;
+  /** 真实默认位人数结构；精确人数是开局身份的一部分。 */
+  positionGroupCounts: Record<string, number>;
+  primaryCategory: string;
+  openingSignature: string;
+  entryEvidence: TacticalEntryEvidence;
+  roundCount: number;
+  winRatePercent: number | null;
+  plantRatePercent: number | null;
+  rounds: Array<{ matchId: string; roundNumber: number; teamKey: string; won: boolean; economy: string; planted: boolean }>;
+}
+
+export function economyEntryOf(economy: string, opponentEconomy: string): EconomyEntry {
+  if (economy === "pistol") return "pistol";
+  if (economy === "full") return opponentEconomy === "full" ? "gun" : "anti_eco";
+  if (economy === "force") return "force";
+  if (economy === "semi") return "semi";
+  return "eco";
+}
+
+export function defaultsBasisKey(defaults: Record<string, number>): string {
+  return Object.entries(defaults)
+    .filter(([, count]) => count > 0)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([id, count]) => `${id}:${count}`)
+    .join("|");
+}
+export const advancedBasisKey = defaultsBasisKey;
+
+/** 稳定默认位身份：按位置责任组 id 排序，并保留真实人数结构。 */
+export function positionGroupSetKey(groups: Record<string, number>): string {
+  return defaultsBasisKey(groups);
+}
+
+export function openingIntentKey(pattern: OpeningPattern): string {
+  const { a, mid, b } = pattern.regionCounts;
+  return `${a}A-${mid}MID-${b}B:${pattern.spread}`;
+}
+
+function teamIdentityOf(row: TacticalPatternRow): string {
+  return row.teamIdentity ?? row.teamName.trim().toLowerCase();
+}
+
+function opponentIdentityOf(row: TacticalPatternRow): string {
+  return row.opponentIdentity ?? row.opponentName.trim().toLowerCase();
+}
+
+export function openingPatternKey(row: TacticalPatternRow): string {
+  return [row.mapName, row.side, openingIntentKey(row.openingPattern), positionGroupSetKey(row.openingPattern.positionGroupCounts)].join(":");
+}
+
+/** 单回合真实进点证据。缺少目标点或入口时返回 null，不用 fallback 猜测。 */
+export function entryEvidenceKey(row: TacticalPatternRow): { site: "a" | "b"; combo: string } | null {
+  if (row.side !== "t") return null;
+  const site = row.targetSite;
+  if (!site) return null;
+  const ids = new Set<string>();
+  for (const occurrence of row.siteEntries[site].order) {
+    const id = occurrence.entryChokeId ?? occurrence.routeFamilyId;
+    if (id) ids.add(id);
+  }
+  if (ids.size === 0) return null;
+  return { site, combo: [...ids].sort().join("+") };
+}
+
+/** 兼容既有调用：该函数现在只读取真实进点 evidence，不参与聚类 key。 */
+export function chokeComboOf(row: TacticalPatternRow, site: "a" | "b" | null): string | null {
+  const evidence = entryEvidenceKey(row);
+  return evidence?.site === site ? evidence.combo : null;
+}
+
+export function tacticalClusterKey(row: TacticalPatternRow): string {
+  return [
+    row.side,
+    row.mapName,
+    teamIdentityOf(row),
+    economyEntryOf(row.economy, row.opponentEconomy),
+    openingIntentKey(row.openingPattern),
+    positionGroupSetKey(row.openingPattern.positionGroupCounts) || "-",
+  ].join("|");
+}
+
+function primaryCategoryOf(pattern: OpeningPattern): string {
+  const { a, mid, b } = pattern.regionCounts;
+  const max = Math.max(a, mid, b);
+  const leaders = [a === max ? "A侧" : null, mid === max ? "中路" : null, b === max ? "B侧" : null].filter(Boolean);
+  return leaders.length === 1 ? `${leaders[0]}控图` : "均衡控图";
+}
+
+export function buildTacticalClusters(rows: readonly TacticalPatternRow[]): TacticalCluster[] {
+  const clusters = new Map<string, TacticalCluster>();
+  const entryCounts = new Map<string, Map<string, number>>();
+  for (const row of rows) {
+    const id = tacticalClusterKey(row);
+    const cluster: TacticalCluster = clusters.get(id) ?? {
+      id,
+      mapName: row.mapName,
+      side: row.side,
+      economyEntry: economyEntryOf(row.economy, row.opponentEconomy),
+      teamIdentity: teamIdentityOf(row),
+      teamName: row.teamName,
+      opponentNames: [row.opponentName],
+      opponentIdentities: [opponentIdentityOf(row)],
+      openingIntent: {
+        regionCounts: { ...row.openingPattern.regionCounts },
+        spread: row.openingPattern.spread,
+      },
+      positionGroupCounts: { ...row.openingPattern.positionGroupCounts },
+      primaryCategory: primaryCategoryOf(row.openingPattern),
+      openingSignature: openingPatternKey(row),
+      entryEvidence: { coveredRounds: 0, totalRounds: 0, coveragePercent: 0, routes: [] },
+      roundCount: 0,
+      winRatePercent: null,
+      plantRatePercent: null,
+      rounds: [],
+    };
+    cluster.roundCount += 1;
+    if (!cluster.opponentNames.includes(row.opponentName)) {
+      cluster.opponentNames.push(row.opponentName);
+      cluster.opponentNames.sort((a, b) => a.localeCompare(b));
+    }
+    const opponentIdentity = opponentIdentityOf(row);
+    if (!cluster.opponentIdentities.includes(opponentIdentity)) cluster.opponentIdentities.push(opponentIdentity);
+    cluster.rounds.push({
+      matchId: row.matchId,
+      roundNumber: row.roundNumber,
+      teamKey: row.teamKey,
+      won: row.won,
+      economy: row.economy,
+      planted: row.plant != null,
+    });
+    const evidence = entryEvidenceKey(row);
+    if (evidence) {
+      const counts = entryCounts.get(id) ?? new Map<string, number>();
+      const routeKey = `${evidence.site}:${evidence.combo}`;
+      counts.set(routeKey, (counts.get(routeKey) ?? 0) + 1);
+      entryCounts.set(id, counts);
+    }
+    clusters.set(id, cluster);
+  }
+  const percent = (numerator: number, denominator: number) =>
+    denominator > 0 ? Math.round((numerator / denominator) * 1000) / 10 : 0;
+  return [...clusters.values()]
+    .map((cluster) => {
+      const counts = entryCounts.get(cluster.id) ?? new Map<string, number>();
+      const coveredRounds = [...counts.values()].reduce((sum, count) => sum + count, 0);
+      return {
+        ...cluster,
+        winRatePercent: percent(cluster.rounds.filter((round) => round.won).length, cluster.roundCount),
+        plantRatePercent: percent(cluster.rounds.filter((round) => round.planted).length, cluster.roundCount),
+        entryEvidence: {
+          coveredRounds,
+          totalRounds: cluster.roundCount,
+          coveragePercent: percent(coveredRounds, cluster.roundCount),
+          routes: [...counts.entries()]
+            .map(([key, roundCount]) => ({
+              site: key.slice(0, 1) as "a" | "b",
+              combo: key.slice(2),
+              roundCount,
+              percentOfCovered: percent(roundCount, coveredRounds),
+            }))
+            .sort((a, b) => b.roundCount - a.roundCount || a.site.localeCompare(b.site) || a.combo.localeCompare(b.combo)),
+        },
+      };
+    })
+    .sort((a, b) => b.roundCount - a.roundCount || a.id.localeCompare(b.id));
+}