@cs2dak/presentation 1.0.0 → 2.0.0

package/src/leaderboard.test.ts

@@ -1,84 +1,58 @@
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
-import { loadDemoPackageFromZip } from "@cs2dak/core";
-import { buildSeasonCohort } from "@cs2dak/cohort";
 import { leaderboardMetricKeySchema, seasonLeaderboardModelSchema } from "@cs2dak/contract";
 import { buildSeasonLeaderboardModel } from "./index";
-
-const fixtureDir = fileURLToPath(new URL("../../../fixtures/input/cohort", import.meta.url));
-const integrationTimeoutMs = 20_000;
+import { buildTestSeasonCohortBundle } from "./test-fixtures";
 
 const ALL_METRIC_KEYS = leaderboardMetricKeySchema.options;
 
-async function buildCohort() {
-  const names = (await readdir(fixtureDir)).filter((name) => name.endsWith(".zip")).sort();
-  const demos = await Promise.all(
-    names.map(async (name) => ({
-      matchId: name.replace(/\.zip$/, ""),
-      pkg: await loadDemoPackageFromZip(await readFile(join(fixtureDir, name)))
-    }))
-  );
-  return buildSeasonCohort(demos);
-}
-
 describe("buildSeasonLeaderboardModel", () => {
-  it(
-    "derives a product-neutral leaderboard model from a season cohort bundle",
-    async () => {
-      const bundle = await buildCohort();
-      const model = buildSeasonLeaderboardModel(bundle);
-
-      // schema 自校验 + 元信息透传
-      expect(() => seasonLeaderboardModelSchema.parse(model)).not.toThrow();
-      expect(model.version).toBe("cs2-demo-analysis-kit/leaderboard-0.1");
-      expect(model.matchCount).toBe(bundle.matchCount);
-      expect(model.weightsVersion).toBe(bundle.weightsVersion);
-      expect(model.provenance).toEqual(bundle.provenance);
-
-      // 视图：core/impact/advanced，无独立 Demo tab
-      expect(model.views.map((v) => v.key)).toEqual(["core", "impact", "advanced"]);
-      for (const view of model.views) {
-        // 默认排序列必须真实存在于该视图
-        expect(view.columns.some((c) => c.key === view.defaultSort)).toBe(true);
+  it("derives a product-neutral leaderboard model from a season cohort bundle", () => {
+    const bundle = buildTestSeasonCohortBundle();
+    const model = buildSeasonLeaderboardModel(bundle);
+
+    // schema 自校验 + 元信息透传
+    expect(() => seasonLeaderboardModelSchema.parse(model)).not.toThrow();
+    expect(model.version).toBe("cs2-demo-analysis-kit/leaderboard-0.1");
+    expect(model.matchCount).toBe(bundle.matchCount);
+    expect(model.weightsVersion).toBe(bundle.weightsVersion);
+    expect(model.provenance).toEqual(bundle.provenance);
+
+    // 视图：core/impact/advanced，无独立 Demo tab
+    expect(model.views.map((v) => v.key)).toEqual(["core", "impact", "advanced"]);
+    for (const view of model.views) {
+      // 默认排序列必须真实存在于该视图
+      expect(view.columns.some((c) => c.key === view.defaultSort)).toBe(true);
+    }
+
+    // 每行覆盖全部玩家，且每个指标 key 都有条目（可为 null，但不缺）
+    expect(model.rows).toHaveLength(bundle.players.length);
+    for (const row of model.rows) {
+      for (const key of ALL_METRIC_KEYS) {
+        expect(row.metrics).toHaveProperty(key);
       }
-
-      // 每行覆盖全部玩家，且每个指标 key 都有条目（可为 null，但不缺）
-      expect(model.rows).toHaveLength(bundle.players.length);
-      for (const row of model.rows) {
-        for (const key of ALL_METRIC_KEYS) {
-          expect(row.metrics).toHaveProperty(key);
-        }
-        // 中立性：不暴露数据库/路由字段，只有中立 key
-        expect(row).not.toHaveProperty("userId");
-      }
-    },
-    integrationTimeoutMs
-  );
-
-  it(
-    "preserves null instead of coercing to 0, and matches cohort source values",
-    async () => {
-      const bundle = await buildCohort();
-      const model = buildSeasonLeaderboardModel(bundle);
-
-      const byKey = new Map(model.rows.map((row) => [row.playerKey, row]));
-      for (const player of bundle.players) {
-        const row = byKey.get(player.playerKey)!;
-        // 不重算：rate 字段直接透传 cohort 已重算的值
-        expect(row.metrics.rivalhubRR).toBe(player.accountRR);
-        expect(row.metrics.hltvRating).toBe(player.rrV1);
-        expect(row.metrics.adr).toBe(player.indicators.adr);
-        expect(row.metrics.kast).toBe(player.indicators.kast);
-        // K/D：deaths=0 必须为 null 而非 0/Infinity
-        if (player.indicators.deaths === 0) {
-          expect(row.metrics.kd).toBeNull();
-        } else {
-          expect(row.metrics.kd).toBeCloseTo(player.indicators.kills / player.indicators.deaths, 1);
-        }
+      // 中立性：不暴露数据库/路由字段，只有中立 key
+      expect(row).not.toHaveProperty("userId");
+    }
+  });
+
+  it("preserves null instead of coercing to 0, and matches cohort source values", () => {
+    const bundle = buildTestSeasonCohortBundle();
+    const model = buildSeasonLeaderboardModel(bundle);
+
+    const byKey = new Map(model.rows.map((row) => [row.playerKey, row]));
+    for (const player of bundle.players) {
+      const row = byKey.get(player.playerKey)!;
+      // 不重算：rate 字段直接透传 cohort 已重算的值
+      expect(row.metrics.rivalhubRR).toBe(player.accountRR);
+      expect(row.metrics.hltvRating).toBe(player.rrV1);
+      expect(row.metrics.adr).toBe(player.indicators.adr);
+      expect(row.metrics.kast).toBe(player.indicators.kast);
+      // K/D：deaths=0 必须为 null 而非 0/Infinity
+      if (player.indicators.deaths === 0) {
+        expect(row.metrics.kd).toBeNull();
+      } else {
+        expect(row.metrics.kd).toBeCloseTo(player.indicators.kills / player.indicators.deaths, 1);
       }
-    },
-    integrationTimeoutMs
-  );
+    }
+  });
 });

package/src/map-roles.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import type { PlayerMapRoleEvidence, TeamMapResponsibilityEvidence } from "@cs2dak/contract";
+import { buildPlayerMapRoleProfiles, buildTeamMapRoleMatrices } from "./index.js";
+
+function evidence(playerKey: string, overrides: Partial<PlayerMapRoleEvidence> = {}): PlayerMapRoleEvidence {
+  return {
+    version: 4, playerKey, teamKey: "Team One", mapName: "de_ancient", side: "ct", status: "ready", confidence: 0.9,
+    sample: { observedRounds: 16, eligibleRounds: 16, eligibleSeconds: 320, matchCount: 3, dataQuality: 1, coverage: 1 },
+    matchIds: ["m1", "m2", "m3"],
+    positionGroups: [{ positionGroupId: "a_anchor", seconds: 120, share: 0.7, roundCount: 7 }],
+    spatial: { dominantGroupStability: 0.875, teamRelativeGroupShare: 0.3, isolationSeconds: 4, isolationShare: 0.03, rejoinCount: 0, delayedConvergenceRoundShare: 0, movementSync: 0.6, openingMainComponentShare: 0.4, openingNoUniqueCoreShare: 0, openingIsolatedShare: 0.4, formationShares: { "4+1": 1 } },
+    support: { utilityUses: 0, openingUtilityUses: 0, utilityUsePerRound: 0, openingUtilityUsePerRound: 0 },
+    responsibility: "anchor_tendency", modifiers: ["positionally_stable"],
+    awp: { duty: "primary_awper", eligibleRounds: 16, qualifiedLongGunRounds: 16, freezeOwnershipRounds: 12, activeSeconds: 160, shots: 24, kills: 10, teamActiveShare: 0.8, usageConcentration: 0.8, matchConsistency: 1 },
+    representativeRounds: [{ matchId: "m1", roundNumber: 1, positionGroupId: "a_anchor" }, { matchId: "m2", roundNumber: 1 }, { matchId: "m3", roundNumber: 1 }], basis: ["facts"], limitations: ["approximation"],
+    ...overrides,
+  };
+}
+
+describe("map role presentation", () => {
+  it("never infers IGL and retains a conflicting declaration beside AWPer inference", () => {
+    const profiles = buildPlayerMapRoleProfiles([evidence("p1"), evidence("p1", { mapName: "de_mirage" })], [{ kind: "main_role", playerKey: "p1", role: "igl", priority: "primary", source: "user", provenance: "coach roster" }]);
+    expect(profiles[0]).toMatchObject({ inferredPrimaryRole: "awper", headlineRole: "IGL / AWPer" });
+    expect(profiles[0]?.declaredRoles).toHaveLength(1);
+    expect(profiles[0]?.inferredPrimaryRole).not.toBe("igl");
+  });
+
+  it("uses inferred headline without declared IGL and never lets non-IGL declarations replace it", () => {
+    const profile = buildPlayerMapRoleProfiles([evidence("p1"), evidence("p1", { mapName: "de_mirage" })], [{ kind: "main_role", playerKey: "p1", role: "anchor", priority: "primary", source: "trusted_metadata", provenance: "roster" }])[0]!;
+    expect(profile.headlineRole).toBe("awper");
+    expect(profile.inferredPrimaryRole).toBe("awper");
+  });
+
+  it("projects overlap and unstable coverage without a five-slot template", () => {
+    const first = evidence("p1");
+    const second = evidence("p2", { awp: { ...evidence("p2").awp, duty: "rifler", activeSeconds: 0, teamActiveShare: 0 }, positionGroups: [{ positionGroupId: "a_anchor", seconds: 100, share: 0.6, roundCount: 7 }] });
+    const team: TeamMapResponsibilityEvidence = {
+      version: 4, teamKey: "Team One", mapName: "de_ancient", side: "ct", status: "mixed", confidence: 0.7,
+      players: [first, second], positionOverlap: [{ positionGroupId: "a_anchor", playerKeys: ["p1", "p2"], share: 1 }],
+      positionConcentration: 1, unstableCoverage: true, representativeRounds: first.representativeRounds, basis: ["facts"], limitations: ["no slots"],
+    };
+    const profiles = buildPlayerMapRoleProfiles([first, second]);
+    const matrix = buildTeamMapRoleMatrices([team], profiles)[0]!;
+    expect(matrix).toMatchObject({ positionConcentration: 1, unstableCoverage: true });
+    expect(matrix.players).toHaveLength(2);
+  });
+
+  it("returns mixed rather than ready with a null role when candidates are not separated", () => {
+    const rifle = { ...evidence("p1").awp, duty: "rifler" as const, qualifiedLongGunRounds: 20, freezeOwnershipRounds: 0, activeSeconds: 0, teamActiveShare: 0, matchConsistency: 0 };
+    const ambiguousSpatial = { ...evidence("p1").spatial, dominantGroupStability: 0.4, teamRelativeGroupShare: 0 };
+    const profile = buildPlayerMapRoleProfiles([
+      evidence("p1", { side: "ct", responsibility: "anchor_tendency", spatial: ambiguousSpatial, awp: rifle }),
+      evidence("p1", { side: "t", mapName: "de_mirage", responsibility: "pack", spatial: ambiguousSpatial, awp: rifle }),
+    ])[0]!;
+    expect(profile.status).toBe("mixed");
+    expect(profile.inferredPrimaryRole).toBeNull();
+    expect(profile.runnerUpRole).not.toBeNull();
+  });
+
+  it("does not promote one-map AWP usage to global Primary AWPer", () => {
+    const profile = buildPlayerMapRoleProfiles([evidence("p1")])[0]!;
+    expect(profile.weaponDuty).toBe("secondary_awper");
+    expect(profile.weaponDuty).not.toBe("primary_awper");
+  });
+
+  it("keeps secondary and situational AWP as evidence rather than public headline eligibility", () => {
+    const secondary = { ...evidence("p1").awp, duty: "secondary_awper" as const, qualifiedLongGunRounds: 12, freezeOwnershipRounds: 4, activeSeconds: 40, shots: 6, kills: 3, teamActiveShare: 0.3, matchConsistency: 0.6 };
+    const anchor = buildPlayerMapRoleProfiles([evidence("p1", { awp: secondary })])[0]!;
+    expect(anchor.weaponDuty).toBe("secondary_awper");
+    expect(anchor.roleEvidenceScores.awper).toBeGreaterThan(0.55);
+    expect(anchor.inferredPrimaryRole).toBe("anchor");
+    const situational = buildPlayerMapRoleProfiles([evidence("p1", { awp: { ...secondary, duty: "situational_awper", qualifiedLongGunRounds: 1, freezeOwnershipRounds: 1 } })])[0]!;
+    expect(situational.inferredPrimaryRole).toBe("anchor");
+  });
+
+  it("keeps a reliable primary AWP eligible for the headline", () => {
+    const profile = buildPlayerMapRoleProfiles([evidence("p1"), evidence("p1", { mapName: "de_mirage" })])[0]!;
+    expect(profile.inferredPrimaryRole).toBe("awper");
+    expect(profile.headlineRole).toBe("awper");
+  });
+
+  it("uses complete match coverage rather than the capped representative evidence sample for global AWP duty", () => {
+    const first = evidence("p1", { representativeRounds: [{ matchId: "m1", roundNumber: 1 }] });
+    const second = evidence("p1", { mapName: "de_mirage", representativeRounds: [{ matchId: "m1", roundNumber: 2 }] });
+    expect(buildPlayerMapRoleProfiles([first, second])[0]?.weaponDuty).toBe("primary_awper");
+  });
+
+  it("matches declaration time scope by match occurrence time and preserves missing-time limitations", () => {
+    const declaration = { kind: "main_role", playerKey: "p1", role: "anchor", priority: "primary", source: "self_report", provenance: "public interview", validFrom: "2026-06-01T00:00:00.000Z", validTo: "2026-06-30T23:59:59.000Z" } as const;
+    expect(buildPlayerMapRoleProfiles([evidence("p1")], [declaration], { matchTimes: { m1: "2026-05-01T00:00:00.000Z", m2: "2026-05-02T00:00:00.000Z", m3: "2026-05-03T00:00:00.000Z" } })[0]?.declaredRoles).toHaveLength(0);
+    const missingTime = buildPlayerMapRoleProfiles([evidence("p1")], [declaration])[0]!;
+    expect(missingTime.declaredRoles).toHaveLength(1);
+    expect(missingTime.limitations).toContain("比赛时间缺失；该声明未与时间未知的 evidence 对齐。");
+  });
+
+  it("only aligns time-scoped declarations with rows fully inside the declared interval", () => {
+    const declaration = { kind: "main_role", playerKey: "p1", role: "anchor", priority: "primary", source: "self_report", provenance: "public interview", validFrom: "2026-06-01T00:00:00.000Z", validTo: "2026-06-30T23:59:59.000Z" } as const;
+    const before = evidence("p1", { matchIds: ["m1"], representativeRounds: [{ matchId: "m1", roundNumber: 1 }], side: "ct" });
+    const within = evidence("p1", { matchIds: ["m4"], representativeRounds: [{ matchId: "m4", roundNumber: 1 }], side: "t" });
+    const profile = buildPlayerMapRoleProfiles([before, within], [declaration], { matchTimes: { m1: "2026-05-01T00:00:00.000Z", m4: "2026-06-15T00:00:00.000Z" } })[0]!;
+    expect(profile.declaredRoles).toHaveLength(1);
+    expect(profile.roleAlignments[0]?.ctSide).toContain("unknown");
+
+    const mixed = buildPlayerMapRoleProfiles([evidence("p1", { matchIds: ["m1", "m4"] })], [declaration], { matchTimes: { m1: "2026-05-01T00:00:00.000Z", m4: "2026-06-15T00:00:00.000Z" } })[0]!;
+    expect(mixed.roleAlignments[0]?.sampleLimitations).toContain("聚合 evidence 跨越声明日期；为避免混入期外样本，未纳入该行。");
+  });
+
+  it("isolates the same player across canonical team identities and aligns declarations only with their scoped rows", () => {
+    const teamOne = evidence("p1", { teamKey: "Team One", mapName: "de_ancient", responsibility: "anchor_tendency" });
+    const teamTwo = evidence("p1", { teamKey: "Team Two", mapName: "de_mirage", side: "t", responsibility: "late_joining", awp: { ...evidence("p1").awp, duty: "rifler", activeSeconds: 0, teamActiveShare: 0, matchConsistency: 0 } });
+    const declaration = { kind: "main_role", playerKey: "p1", teamKey: "Team Two", mapName: "de_mirage", role: "closer", priority: "primary", source: "user", provenance: "coach" } as const;
+    const profiles = buildPlayerMapRoleProfiles([teamOne, teamTwo], [declaration]);
+    expect(profiles).toHaveLength(2);
+    expect(profiles.find((profile) => profile.teamKey === "Team One")?.declaredRoles).toHaveLength(0);
+    const second = profiles.find((profile) => profile.teamKey === "Team Two")!;
+    expect(second.declaredRoles).toHaveLength(1);
+    expect(second.roleAlignments[0]?.ctSide).toContain("unknown");
+  });
+
+  it("does not let a secondary IGL declaration override an AWP headline", () => {
+    const profile = buildPlayerMapRoleProfiles([evidence("p1"), evidence("p1", { mapName: "de_mirage" })], [{ kind: "main_role", playerKey: "p1", role: "igl", priority: "secondary", source: "user", provenance: "coach" }])[0]!;
+    expect(profile.headlineRole).toBe("awper");
+  });
+
+  it("keeps declared weapon duty independent from inferred weapon duty", () => {
+    const profile = buildPlayerMapRoleProfiles([evidence("p1"), evidence("p1", { mapName: "de_mirage" })], [{ kind: "weapon_duty", playerKey: "p1", weaponDuty: "secondary_awper", source: "user", provenance: "coach" }])[0]!;
+    expect(profile.declaredWeaponDuties[0]?.weaponDuty).toBe("secondary_awper");
+    expect(profile.weaponDuty).toBe("primary_awper");
+    expect(profile.weaponDutyAlignments[0]?.overall).toBe("different_observation");
+  });
+});

package/src/map-roles.ts

@@ -0,0 +1,219 @@
+import {
+  playerMapRoleProfileSchema,
+  teamMapRoleMatrixSchema,
+  type DeclaredRole,
+  type EvidenceRef,
+  type InferredMapRole,
+  type MainRoleDeclaration,
+  type MapRoleStatus,
+  type PlayerMapRoleEvidence,
+  type PlayerMapRoleProfile,
+  type RoleDeclaration,
+  type TeamMapResponsibilityEvidence,
+  type TeamMapRoleMatrix,
+  type WeaponDutyDeclaration,
+  type WeaponDuty,
+} from "@cs2dak/contract";
+import { MAP_ROLE_MODEL_VERSION, MAP_ROLE_THRESHOLDS } from "@cs2dak/cohort";
+import { positionGroupDisplay } from "@cs2dak/maps";
+
+const ROLE_ORDER: InferredMapRole[] = ["awper", "anchor", "opener", "closer"];
+
+function rounded(value: number, digits = 3): number { return Number(value.toFixed(digits)); }
+function clamp(value: number): number { return Math.max(0, Math.min(1, value)); }
+
+function evidence(rows: PlayerMapRoleEvidence[]): EvidenceRef[] {
+  return rows.flatMap((row) => row.representativeRounds.map((ref) => ({ ...ref, reason: `${row.mapName} ${row.side.toUpperCase()} 的位置职责代表回合`, role: "example" as const }))).slice(0, 8);
+}
+
+function aggregateStatus(rows: PlayerMapRoleEvidence[]): MapRoleStatus {
+  if (rows.length === 0 || rows.every((row) => row.status === "unknown")) return "unknown";
+  if (rows.every((row) => row.status === "insufficient" || row.status === "unknown")) return "insufficient";
+  return "mixed";
+}
+
+function weighted(rows: PlayerMapRoleEvidence[], value: (row: PlayerMapRoleEvidence) => number): number {
+  const usable = rows.filter((row) => row.status === "ready" || row.status === "mixed");
+  const total = usable.reduce((sum, row) => sum + row.sample.eligibleSeconds * row.sample.dataQuality, 0);
+  return total === 0 ? 0 : usable.reduce((sum, row) => sum + value(row) * row.sample.eligibleSeconds * row.sample.dataQuality, 0) / total;
+}
+
+function globalWeaponDuty(rows: PlayerMapRoleEvidence[]): WeaponDuty | null {
+  const usable = rows.filter((row) => row.awp.activeSeconds != null);
+  if (usable.length === 0) return null;
+  const qualified = usable.reduce((sum, row) => sum + row.awp.qualifiedLongGunRounds, 0);
+  const freeze = usable.reduce((sum, row) => sum + row.awp.freezeOwnershipRounds, 0);
+  const active = usable.reduce((sum, row) => sum + (row.awp.activeSeconds ?? 0), 0);
+  const shots = usable.some((row) => row.awp.shots != null) ? usable.reduce((sum, row) => sum + (row.awp.shots ?? 0), 0) : null;
+  const kills = usable.some((row) => row.awp.kills != null) ? usable.reduce((sum, row) => sum + (row.awp.kills ?? 0), 0) : null;
+  const share = weighted(usable, (row) => row.awp.teamActiveShare ?? 0);
+  const consistency = weighted(usable, (row) => row.awp.matchConsistency ?? 0);
+  const matches = new Set(usable.flatMap((row) => row.matchIds)).size;
+  const maps = new Set(usable.filter((row) => row.awp.duty !== "rifler").map((row) => row.mapName)).size;
+  const ownership = qualified > 0 ? freeze / qualified : 0;
+  const primaryAction = active >= 60 || (shots ?? 0) >= 10 || (kills ?? 0) >= 4;
+  const secondaryAction = active >= 20 || (shots ?? 0) >= 4 || (kills ?? 0) >= 2;
+  if (qualified >= 20 && matches >= 3 && maps >= 2 && ownership >= 0.38 && share >= 0.52 && consistency >= 0.55 && primaryAction) return "primary_awper";
+  if (qualified >= 10 && matches >= 2 && ownership >= 0.18 && share >= 0.2 && consistency >= 0.45 && secondaryAction) return "secondary_awper";
+  return freeze > 0 || active > 0 ? "situational_awper" : "rifler";
+}
+
+function evidenceScores(rows: PlayerMapRoleEvidence[], weaponDuty: WeaponDuty | null): Record<InferredMapRole, number> {
+  const awper = weaponDuty == null ? 0 : ({ primary_awper: 1, secondary_awper: 0.72, situational_awper: 0.3, rifler: 0 } as const)[weaponDuty];
+  const anchor = weighted(rows.filter((row) => row.side === "ct"), (row) => {
+    const relative = clamp(Math.max(0, row.spatial.teamRelativeGroupShare ?? 0) / 0.3);
+    const positionShare = row.positionGroups[0]?.share ?? 0;
+    return clamp((row.spatial.dominantGroupStability ?? 0) * 0.45 + relative * 0.3 + positionShare * 0.25);
+  });
+  const opener = weighted(rows.filter((row) => row.side === "t"), (row) => clamp(
+    (row.spatial.openingMainComponentShare ?? 0) * 0.55
+    + (1 - (row.spatial.openingIsolatedShare ?? 1)) * 0.25
+    + (row.spatial.dominantGroupStability ?? 0) * 0.2,
+  ));
+  const closer = weighted(rows.filter((row) => row.side === "t"), (row) => clamp(
+    (row.spatial.openingIsolatedShare ?? 0) * 0.35
+    + (row.spatial.delayedConvergenceRoundShare ?? 0) * 0.4
+    + (row.spatial.dominantGroupStability ?? 0) * 0.25,
+  ));
+  const headlineCap = weaponDuty === "primary_awper" ? 0.75 : 1;
+  return { awper: rounded(awper), anchor: rounded(anchor * headlineCap), opener: rounded(opener * headlineCap), closer: rounded(closer * headlineCap) };
+}
+
+function rankScores(scores: Record<InferredMapRole, number>): Array<[InferredMapRole, number]> {
+  return ROLE_ORDER.map((role) => [role, scores[role]] as [InferredMapRole, number]).sort((a, b) => b[1] - a[1] || ROLE_ORDER.indexOf(a[0]) - ROLE_ORDER.indexOf(b[0]));
+}
+
+interface ScopedEvidence { rows: PlayerMapRoleEvidence[]; limitations: string[]; relevant: boolean }
+
+function scopedEvidence(declaration: RoleDeclaration, rows: PlayerMapRoleEvidence[], matchTimes: Record<string, string | null>): ScopedEvidence {
+  const base = rows.filter((row) => (declaration.teamKey == null || row.teamKey === declaration.teamKey)
+    && (declaration.mapName == null || row.mapName === declaration.mapName));
+  if (base.length === 0) return { rows: [], limitations: [], relevant: false };
+  if (declaration.validFrom == null && declaration.validTo == null) return { rows: base, limitations: [], relevant: true };
+  const inScope = (matchId: string) => {
+    const time = matchTimes[matchId];
+    return time != null && (declaration.validFrom == null || time >= declaration.validFrom) && (declaration.validTo == null || time <= declaration.validTo);
+  };
+  const unknown = base.some((row) => row.matchIds.some((matchId) => matchTimes[matchId] == null));
+  // Cohort evidence is emitted per match, but retain this strict guard for old or
+  // externally supplied aggregate rows: a partially overlapping row cannot be
+  // attributed to a declaration's time scope without mixing out-of-scope play.
+  const partial = base.some((row) => row.matchIds.some(inScope) && !row.matchIds.every(inScope));
+  const inRange = base.filter((row) => row.matchIds.length > 0 && row.matchIds.every(inScope));
+  return {
+    rows: inRange,
+    limitations: [
+      ...(unknown ? ["比赛时间缺失；该声明未与时间未知的 evidence 对齐。"] : []),
+      ...(partial ? ["聚合 evidence 跨越声明日期；为避免混入期外样本，未纳入该行。"] : []),
+    ],
+    relevant: inRange.length > 0 || unknown || partial,
+  };
+}
+
+function alignment(declaration: MainRoleDeclaration, inferred: InferredMapRole | null, scores: Record<InferredMapRole, number>, rows: PlayerMapRoleEvidence[], scopeLimitations: string[]) {
+  const primary = declaration.priority === "primary" ? declaration.role : null;
+  const secondary = declaration.priority === "secondary" ? [declaration.role] : [];
+  const comparablePrimary = primary === "igl" ? null : primary;
+  const overall = primary == null || inferred == null ? "not_comparable"
+    : comparablePrimary === inferred ? "aligned"
+    : secondary.includes(inferred as DeclaredRole) || (comparablePrimary != null && scores[comparablePrimary] >= 0.5) ? "partially_aligned"
+    : "different_observation";
+  const top = (side: "t" | "ct") => rows.filter((row) => row.side === side).sort((a, b) => b.sample.eligibleSeconds - a.sample.eligibleSeconds)[0]?.responsibility ?? "unknown";
+  return {
+    declaration,
+    declaredPrimary: primary,
+    declaredSecondary: secondary,
+    inferredPrimary: inferred,
+    overall,
+    tSide: `T 方观察职责：${top("t")}`,
+    ctSide: `CT 方观察职责：${top("ct")}`,
+    disagreementReasons: overall === "different_observation" ? ["声明与当前语料中的观察重点不同；这不表示声明填写错误。"] : [],
+    sampleLimitations: [...new Set([...scopeLimitations, ...rows.flatMap((row) => row.limitations)])].slice(0, 4),
+  } as const;
+}
+
+export interface BuildPlayerMapRoleProfilesOptions { matchTimes?: Record<string, string | null> }
+
+function infer(rows: PlayerMapRoleEvidence[]) {
+  const weaponDuty = globalWeaponDuty(rows);
+  const roleEvidenceScores = evidenceScores(rows, weaponDuty);
+  // AWP resemblance remains useful evidence, but only a reliable primary AWP
+  // duty is eligible to win the public main-role headline.
+  const headlineScores = { ...roleEvidenceScores, awper: weaponDuty === "primary_awper" ? roleEvidenceScores.awper : 0 };
+  const ranked = rankScores(headlineScores);
+  const [winner, winnerScore] = ranked[0]!;
+  const [runnerUp, runnerScore] = ranked[1]!;
+  const margin = rounded(winnerScore - runnerScore);
+  const baseStatus = aggregateStatus(rows);
+  const sufficient = rows.some((row) => row.status === "ready" || row.status === "mixed");
+  const reliableWinner = sufficient && winnerScore >= 0.55 && margin >= MAP_ROLE_THRESHOLDS.responsibilitySeparation;
+  const status: MapRoleStatus = baseStatus === "unknown" || baseStatus === "insufficient" ? baseStatus : reliableWinner ? "ready" : "mixed";
+  return { weaponDuty, roleEvidenceScores, winner, runnerUp, margin, sufficient, status, inferredPrimaryRole: status === "ready" ? winner : null };
+}
+
+export function buildPlayerMapRoleProfiles(evidenceRows: PlayerMapRoleEvidence[], declarations: RoleDeclaration[] = [], options: BuildPlayerMapRoleProfilesOptions = {}): PlayerMapRoleProfile[] {
+  const byPlayerTeam = new Map<string, PlayerMapRoleEvidence[]>();
+  for (const row of evidenceRows) {
+    const key = `${row.playerKey}\t${row.teamKey}`;
+    byPlayerTeam.set(key, [...(byPlayerTeam.get(key) ?? []), row]);
+  }
+  return [...byPlayerTeam.entries()].map(([key, rows]) => {
+    const [playerKey, teamKey] = key.split("\t");
+    const scopedDeclarations = declarations
+      .filter((declaration) => declaration.playerKey === playerKey && (declaration.teamKey == null || declaration.teamKey === teamKey))
+      .map((declaration) => ({ declaration, scope: scopedEvidence(declaration, rows, options.matchTimes ?? {}) }))
+      .filter((item) => item.scope.relevant);
+    const declaredRoles = scopedDeclarations.filter((item): item is { declaration: MainRoleDeclaration; scope: ScopedEvidence } => item.declaration.kind === "main_role").map((item) => item.declaration);
+    const declaredWeaponDuties = scopedDeclarations.filter((item): item is { declaration: WeaponDutyDeclaration; scope: ScopedEvidence } => item.declaration.kind === "weapon_duty").map((item) => item.declaration);
+    const automatic = infer(rows);
+    const { weaponDuty, roleEvidenceScores, winner, runnerUp, margin, sufficient, status, inferredPrimaryRole } = automatic;
+    const declaredIgl = scopedDeclarations.some((item) => item.declaration.kind === "main_role" && item.declaration.priority === "primary" && item.declaration.role === "igl" && item.declaration.mapName == null && item.declaration.validFrom == null && item.declaration.validTo == null);
+    const headlineRole = declaredIgl ? inferredPrimaryRole === "awper" ? "IGL / AWPer" : "IGL" : inferredPrimaryRole;
+    const volume = clamp(rows.reduce((sum, row) => sum + row.sample.eligibleRounds, 0) / 40);
+    const quality = weighted(rows, (row) => row.sample.dataQuality);
+    const stability = weighted(rows, (row) => row.awp.matchConsistency ?? row.spatial.dominantGroupStability ?? 0.5);
+    const confidence = status === "unknown" ? 0 : rounded(clamp(volume * 0.3 + quality * 0.3 + margin * 0.25 + stability * 0.15));
+    const roleAlignments = scopedDeclarations
+      .filter((item): item is { declaration: MainRoleDeclaration; scope: ScopedEvidence } => item.declaration.kind === "main_role")
+      .map(({ declaration, scope }) => {
+        const observed = scope.rows.length ? infer(scope.rows) : null;
+        return alignment(declaration, observed?.inferredPrimaryRole ?? null, observed?.roleEvidenceScores ?? roleEvidenceScores, scope.rows, scope.limitations);
+      });
+    const weaponDutyAlignments = scopedDeclarations
+      .filter((item): item is { declaration: WeaponDutyDeclaration; scope: ScopedEvidence } => item.declaration.kind === "weapon_duty")
+      .map(({ declaration, scope }) => {
+        const observed = scope.rows.length ? infer(scope.rows).weaponDuty : null;
+        return { declaration, observedWeaponDuty: observed, overall: observed == null ? "not_comparable" : observed === declaration.weaponDuty ? "aligned" : "different_observation", sampleLimitations: scope.limitations } as const;
+      });
+    return playerMapRoleProfileSchema.parse({
+      version: "cs2-demo-analysis-kit/player-map-role-profile-5.0", playerKey, teamKey,
+      declaredRoles, declaredWeaponDuties,
+      inferredPrimaryRole, runnerUpRole: sufficient ? runnerUp : null, separationMargin: sufficient ? margin : null, roleEvidenceScores,
+      headlineRole, status, confidence, weaponDuty,
+      positionGroupDisplay: rows.flatMap((row) => row.positionGroups.map((group) => ({ mapName: row.mapName, side: row.side, positionGroupId: group.positionGroupId, ...positionGroupDisplay(row.mapName, row.side, group.positionGroupId) }))),
+      roleAlignments, weaponDutyAlignments,
+      perMapEvidence: rows.sort((a, b) => a.teamKey.localeCompare(b.teamKey) || a.mapName.localeCompare(b.mapName) || a.side.localeCompare(b.side)),
+      evidence: evidence(rows),
+      basis: [`${MAP_ROLE_MODEL_VERSION}：headline 直接由连续 evidence 计算，不重复叠加离散职责标签。`, "倾向分不是概率；人工声明与自动观察独立保存。"],
+      limitations: ["IGL 无法由 demo 统计验证。", ...[...new Set(scopedDeclarations.flatMap((item) => item.scope.limitations))]],
+    });
+  }).sort((a, b) => a.playerKey.localeCompare(b.playerKey) || a.teamKey.localeCompare(b.teamKey));
+}
+
+export function buildTeamMapRoleMatrices(evidenceRows: TeamMapResponsibilityEvidence[], profiles: PlayerMapRoleProfile[]): TeamMapRoleMatrix[] {
+  const profileByKey = new Map(profiles.map((profile) => [`${profile.playerKey}\t${profile.teamKey}`, profile]));
+  return evidenceRows.map((row) => teamMapRoleMatrixSchema.parse({
+    version: "cs2-demo-analysis-kit/team-map-role-matrix-4.0", teamKey: row.teamKey, mapName: row.mapName, side: row.side,
+    status: row.status, confidence: row.confidence,
+    players: row.players.map((player) => ({
+      playerKey: player.playerKey,
+      primaryPositionGroups: player.positionGroups.slice(0, 3).map((group) => ({ ...group, ...positionGroupDisplay(row.mapName, row.side, group.positionGroupId) })),
+      responsibility: player.responsibility, modifiers: player.modifiers,
+      sampleRounds: player.sample.eligibleRounds, confidence: player.confidence,
+      weaponDuty: profileByKey.get(`${player.playerKey}\t${row.teamKey}`)?.weaponDuty ?? null, evidence: evidence([player]),
+    })),
+    positionOverlap: row.positionOverlap, positionConcentration: row.positionConcentration, unstableCoverage: row.unstableCoverage,
+    representativeRounds: row.representativeRounds.map((ref) => ({ ...ref, reason: `${row.mapName} ${row.side.toUpperCase()} 队伍职责代表回合`, role: "example" as const })),
+    basis: row.basis, limitations: row.limitations,
+  })).sort((a, b) => a.teamKey.localeCompare(b.teamKey) || a.mapName.localeCompare(b.mapName) || a.side.localeCompare(b.side));
+}

package/src/player-map-pool.ts

@@ -0,0 +1,28 @@
+import { playerMapPoolRowSchema, type PlayerMapPoolRow, type PlayerMapRoleProfile, type SupportedMapName } from "@cs2dak/contract";
+
+export interface PlayerMapPerformanceInput {
+  mapName: SupportedMapName; matchCount: number; roundCount: number; wins: number; losses: number;
+  rr: number | null; adr: number | null; kast: number | null; openingKills: number; openingDeaths: number; mainWeapon: string | null;
+}
+
+export function buildPlayerMapPool(performance: PlayerMapPerformanceInput[], profile: PlayerMapRoleProfile | null): PlayerMapPoolRow[] {
+  return performance.map((row) => {
+    const roleRows = profile?.perMapEvidence.filter((evidence) => evidence.mapName === row.mapName) ?? [];
+    const side = (value: "t" | "ct") => roleRows.find((evidence) => evidence.side === value);
+    const label = (value: "t" | "ct") => {
+      const evidence = side(value); const group = evidence?.positionGroups[0];
+      if (!group) return null;
+      return profile?.positionGroupDisplay.find((display) => display.mapName === row.mapName && display.side === value && display.positionGroupId === group.positionGroupId)?.displayName ?? "未映射位置";
+    };
+    const qualityWeight = roleRows.reduce((sum, evidence) => sum + evidence.sample.eligibleSeconds, 0);
+    const weighted = (pick: (evidence: (typeof roleRows)[number]) => number) => qualityWeight === 0 ? 0 : roleRows.reduce((sum, evidence) => sum + pick(evidence) * evidence.sample.eligibleSeconds, 0) / qualityWeight;
+    return playerMapPoolRowSchema.parse({
+      ...row, winRate: row.matchCount ? row.wins / row.matchCount : null,
+      globalWeaponDuty: profile?.weaponDuty ?? null,
+      mapSideAwpUsage: roleRows.map((evidence) => ({ side: evidence.side, duty: evidence.awp.duty, qualifiedRounds: evidence.awp.qualifiedLongGunRounds, activeSeconds: evidence.awp.activeSeconds })),
+      tPositionGroup: label("t"), ctPositionGroup: label("ct"), tResponsibility: side("t")?.responsibility ?? "unknown", ctResponsibility: side("ct")?.responsibility ?? "unknown",
+      sampleQuality: weighted((evidence) => evidence.sample.dataQuality), confidence: weighted((evidence) => evidence.confidence),
+      evidence: roleRows.flatMap((evidence) => evidence.representativeRounds.map((ref) => ({ ...ref, reason: `${row.mapName} 地图池代表回合`, role: "example" as const }))).slice(0, 6),
+    });
+  }).sort((a, b) => b.matchCount - a.matchCount || a.mapName.localeCompare(b.mapName));
+}