@cs2dak/contract 0.2.1 → 1.1.0

package/src/leaderboard.ts

@@ -0,0 +1,102 @@
+import type { PrismResult } from "@rivalhub/rival-rating";
+import { z } from "zod";
+import { teamKeySchema } from "cs2-demo-format";
+import { seasonCohortBundleSchema } from "./cohort.js";
+
+/**
+ * 赛季排行榜展示模型。由 @cs2dak/presentation 从 SeasonCohortBundle 派生，
+ * 吸收 RivalHub 排行榜的产品信息架构（分栏、标签、默认排序），但：
+ * - 不含数据库/权限/路由语义（规则 8）；身份用中立的 playerKey/teamKeys。
+ * - 缺失指标保持 null，不伪造 0（规则 6）。
+ * - 不计算评分公式；rrV1/accountRR/prism 均来自 cohort 已接线的 rival-rating 结果（规则 5）。
+ */
+
+/** 排行榜可展示的指标 key。值统一存原始量纲，缩放与单位由 format 决定。 */
+export const leaderboardMetricKeySchema = z.enum([
+  "maps",
+  // 评分门面
+  "rivalhubRR", // accountRR（绝对刻度 RivalHub RR）
+  "hltvRating", // rrV1（HLTV Rating 2.0 量纲，已被逆向验证）
+  // core
+  "adr",
+  "kd",
+  "kpr",
+  "hsPercent",
+  // impact（产量家族：每 100 回合 X 次）
+  "firstKillPer100",
+  "multiKillPer100",
+  "clutchPer100",
+  "openingDuelWinRate",
+  // advanced
+  "kast",
+  "utilityDamagePerRound",
+  "awpKillsPerRound",
+  "awpKillRate",
+  "flashAssistPerRound",
+  "tradeKillRate"
+]);
+
+/**
+ * 渲染格式。所有百分比类指标在 builder 中已统一为 0–100 刻度，故只有一个 percent 格式：
+ * - integer: 整数
+ * - rating:  2 位小数（RR / HLTV）
+ * - adr:     1 位小数
+ * - ratio:   2 位小数（K/D、KPR、每 100 回合产量 FK/MK/C、每回合计数）
+ * - percent: 值已是 0–100，1 位小数 + %（HS% / KAST% / Entry% / AWP%）
+ */
+export const leaderboardFormatSchema = z.enum([
+  "integer",
+  "rating",
+  "adr",
+  "ratio",
+  "percent"
+]);
+
+export const leaderboardColumnSchema = z.object({
+  key: leaderboardMetricKeySchema,
+  label: z.string(),
+  format: leaderboardFormatSchema,
+  /** 列说明 / tooltip；无则 null。 */
+  description: z.string().nullable()
+});
+
+export const leaderboardViewKeySchema = z.enum(["core", "impact", "advanced"]);
+
+export const leaderboardViewSchema = z.object({
+  key: leaderboardViewKeySchema,
+  label: z.string(),
+  /** 默认排序列（始终降序）。 */
+  defaultSort: leaderboardMetricKeySchema,
+  columns: z.array(leaderboardColumnSchema)
+});
+
+export const seasonLeaderboardRowSchema = z.object({
+  playerKey: z.string(),
+  name: z.string(),
+  steamIds: z.array(z.string()),
+  externalUserId: z.string().nullable(),
+  teamKeys: z.array(teamKeySchema),
+  mapCount: z.number().int().positive(),
+  confidence: z.number().min(0).max(1),
+  /** 每个指标 key 都有值；不可得为 null（不伪造 0）。 */
+  metrics: z.record(leaderboardMetricKeySchema, z.number().nullable()),
+  /** PRISM 风格画像，仅表达风格，不进入排序；缺失为 null。 */
+  prism: z.custom<PrismResult>().nullable()
+});
+
+export const seasonLeaderboardModelSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/leaderboard-0.1"),
+  weightsVersion: z.string(),
+  matchCount: z.number().int().nonnegative(),
+  provenance: seasonCohortBundleSchema.shape.provenance,
+  views: z.array(leaderboardViewSchema),
+  rows: z.array(seasonLeaderboardRowSchema)
+});
+
+export type LeaderboardMetricKey = z.infer<typeof leaderboardMetricKeySchema>;
+export type LeaderboardFormat = z.infer<typeof leaderboardFormatSchema>;
+export type LeaderboardColumn = z.infer<typeof leaderboardColumnSchema>;
+export type LeaderboardViewKey = z.infer<typeof leaderboardViewKeySchema>;
+export type LeaderboardView = z.infer<typeof leaderboardViewSchema>;
+export type SeasonLeaderboardRow = z.infer<typeof seasonLeaderboardRowSchema>;
+export type SeasonLeaderboardModel = z.infer<typeof seasonLeaderboardModelSchema>;

package/src/map-intelligence.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+import { playerIndexSchema, sideSchema, steamId64Schema, teamKeySchema } from "./upstream.js";
+
+/** Bump when the compact map-intelligence producer changes its factual meaning. */
+export const MAP_INTELLIGENCE_FACT_VERSION = 6;
+export const OPENING_RESPONSIBILITY_WINDOW_VERSION = 1;
+export const CT_ROTATION_FACT_VERSION = 1;
+
+const availabilitySchema = z.enum(["available", "degraded", "missing"]);
+
+export const mapIntelligenceAvailabilitySchema = z.object({
+  replay: availabilitySchema,
+  nav: availabilitySchema,
+  callouts: availabilitySchema,
+  shots: availabilitySchema,
+});
+
+const tacticalRegionSchema = z.enum(["a", "b", "mid"]);
+export const ctRotationAvailabilitySchema = mapIntelligenceAvailabilitySchema.extend({
+  combatTimeline: availabilitySchema,
+});
+
+export const positionGroupDwellSchema = z.object({
+  positionGroupId: z.string().min(1),
+  seconds: z.number().nonnegative(),
+  share: z.number().min(0).max(1),
+});
+
+export const responsibilityWindowSchema = z.object({
+  version: z.literal(OPENING_RESPONSIBILITY_WINDOW_VERSION),
+  startTick: z.number().int().nonnegative(),
+  endTick: z.number().int().nonnegative(),
+  configuredSeconds: z.number().positive(),
+});
+
+export const openingPathPointSchema = z.object({
+  tick: z.number().int().nonnegative(),
+  callout: z.string().nullable(),
+  positionGroupId: z.string().nullable(),
+  x: z.number(), y: z.number(), z: z.number(),
+});
+
+/** A compact, locatable period where a player was separated from their team component. */
+export const isolationSegmentSchema = z.object({
+  startTick: z.number().int().nonnegative(),
+  endTick: z.number().int().nonnegative(),
+  seconds: z.number().nonnegative(),
+});
+
+/** A conservative isolated-to-stable-group transition inside one round. */
+export const delayedConvergenceSchema = z.object({
+  tick: z.number().int().nonnegative(),
+  priorIsolationSeconds: z.number().nonnegative(),
+  joinedComponentSize: z.number().int().min(3),
+  persistenceSeconds: z.number().positive(),
+});
+
+export const playerPositionRoundFactSchema = z.object({
+  analysisVersion: z.literal(MAP_INTELLIGENCE_FACT_VERSION),
+  matchId: z.string().min(1),
+  mapName: z.string().min(1),
+  roundNumber: z.number().int().positive(),
+  teamKey: teamKeySchema,
+  side: sideSchema,
+  playerIndex: playerIndexSchema,
+  steamId64: steamId64Schema,
+  economyType: z.enum(["pistol", "eco", "semi", "force", "full"]).nullable(),
+  openingWindow: responsibilityWindowSchema.nullable(),
+  openingEligibleSeconds: z.number().nonnegative().nullable(),
+  openingPositionGroupDwell: z.array(positionGroupDwellSchema),
+  openingMeanComponentSize: z.number().positive().nullable(),
+  openingIsolationSeconds: z.number().nonnegative().nullable(),
+  openingUtilityUseCount: z.number().int().nonnegative(),
+  openingPath: z.array(openingPathPointSchema).max(8),
+  /** Full-round movement/action coverage, from freeze end until death or round end. */
+  eligibleSeconds: z.number().nonnegative().nullable(),
+  positionGroupDwell: z.array(positionGroupDwellSchema),
+  unresolvedCalloutSeconds: z.number().nonnegative().nullable(),
+  calloutCoverage: z.number().min(0).max(1).nullable(),
+  meanNearestTeammateDistance: z.number().nonnegative().nullable(),
+  meanTeamCentroidDistance: z.number().nonnegative().nullable(),
+  meanComponentSize: z.number().positive().nullable(),
+  isolationSegments: z.array(isolationSegmentSchema),
+  rejoinTicks: z.array(z.number().int().nonnegative()),
+  delayedConvergences: z.array(delayedConvergenceSchema),
+  movementSync: z.number().min(-1).max(1).nullable(),
+  utilityUseCount: z.number().int().nonnegative(),
+  freezeAwpOwnership: z.boolean().nullable(),
+  activeAwpSeconds: z.number().nonnegative().nullable(),
+  awpShots: z.number().int().nonnegative().nullable(),
+  awpKills: z.number().int().nonnegative().nullable(),
+  availability: mapIntelligenceAvailabilitySchema,
+});
+
+export const teamShapeWindowSchema = z.object({
+  startTick: z.number().int().nonnegative(),
+  endTick: z.number().int().nonnegative(),
+  coverageSeconds: z.number().nonnegative(),
+  /** Descending component sizes, e.g. [4, 1] for a 4+1. */
+  componentSizes: z.array(z.number().int().positive()).min(1),
+  partition: z.string().min(1),
+  componentPlayerIndices: z.array(z.array(playerIndexSchema).min(1)).min(1),
+});
+
+export const teamShapeRoundFactSchema = z.object({
+  analysisVersion: z.literal(MAP_INTELLIGENCE_FACT_VERSION),
+  matchId: z.string().min(1),
+  mapName: z.string().min(1),
+  roundNumber: z.number().int().positive(),
+  teamKey: teamKeySchema,
+  side: sideSchema,
+  openingWindow: responsibilityWindowSchema.nullable(),
+  openingWindows: z.array(teamShapeWindowSchema),
+  /** Full-round component continuity windows. */
+  coverageSeconds: z.number().nonnegative().nullable(),
+  windows: z.array(teamShapeWindowSchema),
+  availability: mapIntelligenceAvailabilitySchema,
+});
+
+export const teamAwpRoundFactSchema = z.object({
+  analysisVersion: z.literal(MAP_INTELLIGENCE_FACT_VERSION),
+  matchId: z.string().min(1),
+  mapName: z.string().min(1),
+  roundNumber: z.number().int().positive(),
+  teamKey: teamKeySchema,
+  side: sideSchema,
+  economyType: z.enum(["pistol", "eco", "semi", "force", "full"]),
+  opponentEconomyType: z.enum(["pistol", "eco", "semi", "force", "full"]),
+  scorePhase: z.enum(["first_half", "second_half", "overtime"]),
+  won: z.boolean(),
+  roundStartAwpPlayerIndices: z.array(playerIndexSchema),
+  doubleAwpActiveSeconds: z.number().nonnegative().nullable(),
+  awpActiveSeconds: z.number().nonnegative().nullable(),
+  awpShots: z.number().int().nonnegative().nullable(),
+  awpKills: z.number().int().nonnegative().nullable(),
+  awpDamage: z.number().nonnegative().nullable(),
+  openingKills: z.number().int().nonnegative(),
+  openingDeaths: z.number().int().nonnegative(),
+  availability: mapIntelligenceAvailabilitySchema,
+});
+
+/** One CT player-round observation. It records response facts, never a role label. */
+export const ctRotationRoundFactSchema = z.object({
+  analysisVersion: z.literal(MAP_INTELLIGENCE_FACT_VERSION),
+  factVersion: z.literal(CT_ROTATION_FACT_VERSION),
+  matchId: z.string().min(1),
+  mapName: z.string().min(1),
+  roundNumber: z.number().int().positive(),
+  teamKey: teamKeySchema,
+  side: z.literal("ct"),
+  playerIndex: playerIndexSchema,
+  steamId64: steamId64Schema,
+  initialPositionGroupId: z.string().min(1).nullable(),
+  initialRegion: tacticalRegionSchema.nullable(),
+  initialPositionGroupShare: z.number().min(0).max(1).nullable(),
+  initialResponsibilityResolved: z.boolean(),
+  initialWindowEligibleSeconds: z.number().nonnegative().nullable(),
+  firstOwnAreaContactTick: z.number().int().nonnegative().nullable(),
+  firstOtherAreaContactTick: z.number().int().nonnegative().nullable(),
+  firstTeamContactTick: z.number().int().nonnegative().nullable(),
+  leftInitialPositionGroupTick: z.number().int().nonnegative().nullable(),
+  /** Signed: negative means the stable departure preceded the first observed other-area contact. */
+  leaveDelayAfterFirstOtherAreaContactSeconds: z.number().nullable(),
+  firstStableDestinationPositionGroupId: z.string().min(1).nullable(),
+  firstStableDestinationRegion: tacticalRegionSchema.nullable(),
+  crossedResponsibilityArea: z.boolean().nullable(),
+  returnedToInitialPositionGroup: z.boolean().nullable(),
+  transitToStableDestinationSeconds: z.number().nonnegative().nullable(),
+  /** Competition rank by observed departure tick; simultaneous departures share a rank. */
+  crossAreaDepartureOrder: z.number().int().positive().nullable(),
+  firstCrossAreaDeparture: z.boolean().nullable(),
+  priorCrossAreaDeparturesAlive: z.number().int().nonnegative().nullable(),
+  initialAreaStillCovered: z.boolean().nullable(),
+  deathTick: z.number().int().nonnegative().nullable(),
+  censoredByDeath: z.boolean().nullable(),
+  roundEndTick: z.number().int().nonnegative(),
+  availability: ctRotationAvailabilitySchema,
+});
+
+/** Compact per-match replay-derived map facts. It intentionally contains no role conclusion. */
+export const matchMapIntelligenceFactsSchema = z.object({
+  analysisVersion: z.literal(MAP_INTELLIGENCE_FACT_VERSION),
+  matchId: z.string().min(1),
+  mapName: z.string().min(1),
+  playerPositionRounds: z.array(playerPositionRoundFactSchema),
+  teamShapeRounds: z.array(teamShapeRoundFactSchema),
+  teamAwpRounds: z.array(teamAwpRoundFactSchema),
+  ctRotationRounds: z.array(ctRotationRoundFactSchema),
+});
+
+export type MapIntelligenceAvailability = z.infer<typeof mapIntelligenceAvailabilitySchema>;
+export type PositionGroupDwell = z.infer<typeof positionGroupDwellSchema>;
+export type ResponsibilityWindow = z.infer<typeof responsibilityWindowSchema>;
+export type IsolationSegment = z.infer<typeof isolationSegmentSchema>;
+export type DelayedConvergence = z.infer<typeof delayedConvergenceSchema>;
+export type PlayerPositionRoundFact = z.infer<typeof playerPositionRoundFactSchema>;
+export type TeamShapeWindow = z.infer<typeof teamShapeWindowSchema>;
+export type TeamShapeRoundFact = z.infer<typeof teamShapeRoundFactSchema>;
+export type TeamAwpRoundFact = z.infer<typeof teamAwpRoundFactSchema>;
+export type CtRotationAvailability = z.infer<typeof ctRotationAvailabilitySchema>;
+export type CtRotationRoundFact = z.infer<typeof ctRotationRoundFactSchema>;
+export type MatchMapIntelligenceFacts = z.infer<typeof matchMapIntelligenceFactsSchema>;

package/src/map-role.ts

@@ -0,0 +1,317 @@
+import { z } from "zod";
+import { evidenceRefSchema } from "./evidence.js";
+
+/** Bump when aggregation or role-selection semantics change. */
+export const MAP_ROLE_EVIDENCE_VERSION = 4;
+export const T_RESPONSIBILITY_RESEARCH_PROJECTION_VERSION = "cs2-demo-analysis-kit/t-responsibility-research-projection-1.0";
+
+/** The supported active-duty pool. Unknown maps are deliberately not generalized. */
+export const supportedMapNameSchema = z.enum([
+  "de_ancient", "de_anubis", "de_dust2", "de_inferno", "de_mirage", "de_nuke", "de_overpass"
+]);
+export const mapRoleStatusSchema = z.enum(["ready", "mixed", "insufficient", "unknown"]);
+export const inferredMapRoleSchema = z.enum(["awper", "anchor", "opener", "closer"]);
+export const declaredRoleSchema = z.enum(["igl", "awper", "anchor", "opener", "closer"]);
+export const weaponDutySchema = z.enum(["primary_awper", "secondary_awper", "situational_awper", "rifler"]);
+export const teamResponsibilitySchema = z.enum([
+  "pack", "extremity", "late_joining", "stable_default",
+  "anchor_tendency", "component_mobile", "independent_mobile", "stable_position",
+  "mixed", "unknown",
+]);
+export const roleModifierSchema = z.enum(["utility_supportive", "positionally_stable", "spatially_isolated", "component_mobile"]);
+export const tResponsibilityResearchCandidateSchema = z.enum(["pack", "lurker", "flexible"]);
+
+export const tResponsibilityResearchFeaturesSchema = z.object({
+  dominantGroupStability: z.number().min(0).max(1).nullable(),
+  teamRelativeGroupShare: z.number().min(-1).max(1).nullable(),
+  openingIsolatedShare: z.number().min(0).max(1).nullable(),
+  isolationShare: z.number().min(0).max(1).nullable(),
+  delayedConvergenceShare: z.number().min(0).max(1).nullable(),
+  movementSync: z.number().min(-1).max(1).nullable(),
+  positionTopShare: z.number().min(0).max(1).nullable(),
+  openingLargestShare: z.number().min(0).max(1).nullable(),
+  fullLargestShare: z.number().min(0).max(1).nullable(),
+  meanTeamCentroidDistance: z.number().nonnegative().nullable(),
+  openingPathDisplacement: z.number().nonnegative().nullable(),
+  openingPathTransitions: z.number().nonnegative().nullable(),
+  openingPositionEntropy: z.number().min(0).max(1).nullable(),
+  fullPositionEntropy: z.number().min(0).max(1).nullable(),
+  rejoinsPerMinute: z.number().nonnegative().nullable(),
+});
+
+/** Product-neutral declaration scope. Storage ids, namespaces and timestamps intentionally do not belong here. */
+const declarationScopeSchema = z.object({
+  playerKey: z.string().min(1),
+  source: z.enum(["user", "self_report", "organizer", "event_package", "trusted_metadata"]),
+  mapName: supportedMapNameSchema.optional(),
+  teamKey: z.string().min(1).optional(),
+  validFrom: z.string().datetime().optional(),
+  validTo: z.string().datetime().optional(),
+  provenance: z.string().min(1),
+}).strict();
+
+/** A declared tactical role. priority belongs only to this kind of declaration. */
+export const mainRoleDeclarationSchema = declarationScopeSchema.extend({
+  kind: z.literal("main_role"),
+  role: declaredRoleSchema,
+  priority: z.enum(["primary", "secondary"]),
+});
+
+/** A declared weapon duty. It is deliberately independent from tactical-role priority. */
+export const weaponDutyDeclarationSchema = declarationScopeSchema.extend({
+  kind: z.literal("weapon_duty"),
+  weaponDuty: weaponDutySchema,
+});
+
+export const roleDeclarationSchema = z.discriminatedUnion("kind", [mainRoleDeclarationSchema, weaponDutyDeclarationSchema]).superRefine((value, context) => {
+  if (value.validFrom != null && value.validTo != null && value.validFrom > value.validTo) context.addIssue({ code: z.ZodIssueCode.custom, message: "validFrom must not be after validTo" });
+});
+
+export const roleEvidenceLocatorSchema = z.object({
+  matchId: z.string().min(1),
+  roundNumber: z.number().int().positive(),
+  positionGroupId: z.string().min(1).optional(),
+});
+
+/**
+ * Same-event research projection. It is intentionally separate from
+ * PlayerMapRoleEvidence.responsibility and is not a production role conclusion.
+ */
+export const tResponsibilityResearchProjectionSchema = z.object({
+  version: z.literal(T_RESPONSIBILITY_RESEARCH_PROJECTION_VERSION),
+  modelId: z.literal("cologne-major-2026/parsimonious-v1-full-fit"),
+  playerKey: z.string().min(1),
+  teamKey: z.string().min(1),
+  side: z.literal("t"),
+  status: mapRoleStatusSchema,
+  candidate: tResponsibilityResearchCandidateSchema.nullable(),
+  packScore: z.number().min(0).max(1).nullable(),
+  lurkerScore: z.number().min(0).max(1).nullable(),
+  confidence: z.number().min(0).max(1).nullable(),
+  sample: z.object({
+    observedRounds: z.number().int().nonnegative(),
+    eligibleRounds: z.number().int().nonnegative(),
+    eligibleSeconds: z.number().nonnegative(),
+    matchCount: z.number().int().nonnegative(),
+    mapCount: z.number().int().nonnegative(),
+    dataQuality: z.number().min(0).max(1).nullable(),
+  }),
+  features: tResponsibilityResearchFeaturesSchema,
+  matchIds: z.array(z.string().min(1)),
+  representativeRounds: z.array(roleEvidenceLocatorSchema).max(8),
+  basis: z.array(z.string()),
+  limitations: z.array(z.string()),
+});
+
+export const mapPositionGroupEvidenceSchema = z.object({
+  positionGroupId: z.string().min(1),
+  seconds: z.number().nonnegative(),
+  share: z.number().min(0).max(1),
+  roundCount: z.number().int().nonnegative(),
+});
+
+export const awpResponsibilityEvidenceSchema = z.object({
+  duty: weaponDutySchema,
+  eligibleRounds: z.number().int().nonnegative(),
+  freezeOwnershipRounds: z.number().int().nonnegative(),
+  activeSeconds: z.number().nonnegative().nullable(),
+  shots: z.number().int().nonnegative().nullable(),
+  kills: z.number().int().nonnegative().nullable(),
+  teamActiveShare: z.number().min(0).max(1).nullable(),
+  /** Concentration/exclusivity of observed AWP active time inside this team/map/side cell. */
+  usageConcentration: z.number().min(0).max(1).nullable(),
+  matchConsistency: z.number().min(0).max(1).nullable(),
+  qualifiedLongGunRounds: z.number().int().nonnegative(),
+});
+
+/** One identity × canonical team × map × side evidence cell. No role conclusion is stored here. */
+export const playerMapRoleEvidenceSchema = z.object({
+  version: z.literal(MAP_ROLE_EVIDENCE_VERSION),
+  playerKey: z.string().min(1),
+  teamKey: z.string().min(1),
+  mapName: supportedMapNameSchema,
+  side: z.enum(["t", "ct"]),
+  status: mapRoleStatusSchema,
+  confidence: z.number().min(0).max(1),
+  sample: z.object({
+    observedRounds: z.number().int().nonnegative(),
+    eligibleRounds: z.number().int().nonnegative(),
+    eligibleSeconds: z.number().nonnegative(),
+    matchCount: z.number().int().nonnegative(),
+    dataQuality: z.number().min(0).max(1),
+    coverage: z.number().min(0).max(1).nullable(),
+  }),
+  /** Complete compact match coverage for aggregation and declaration time scope; not an evidence sample. */
+  matchIds: z.array(z.string().min(1)),
+  positionGroups: z.array(mapPositionGroupEvidenceSchema),
+  spatial: z.object({
+    dominantGroupStability: z.number().min(0).max(1).nullable(),
+    teamRelativeGroupShare: z.number().min(-1).max(1).nullable(),
+    isolationSeconds: z.number().nonnegative().nullable(),
+    isolationShare: z.number().min(0).max(1).nullable(),
+    rejoinCount: z.number().int().nonnegative().nullable(),
+    delayedConvergenceRoundShare: z.number().min(0).max(1).nullable(),
+    movementSync: z.number().min(-1).max(1).nullable(),
+    openingMainComponentShare: z.number().min(0).max(1).nullable(),
+    openingNoUniqueCoreShare: z.number().min(0).max(1).nullable(),
+    openingIsolatedShare: z.number().min(0).max(1).nullable(),
+    formationShares: z.record(z.number().min(0).max(1)),
+  }),
+  support: z.object({
+    utilityUses: z.number().int().nonnegative(),
+    openingUtilityUses: z.number().int().nonnegative(),
+    utilityUsePerRound: z.number().nonnegative(),
+    openingUtilityUsePerRound: z.number().nonnegative(),
+  }),
+  responsibility: teamResponsibilitySchema,
+  modifiers: z.array(roleModifierSchema),
+  awp: awpResponsibilityEvidenceSchema,
+  representativeRounds: z.array(roleEvidenceLocatorSchema).max(5),
+  basis: z.array(z.string()),
+  limitations: z.array(z.string()),
+});
+
+export const teamMapResponsibilityEvidenceSchema = z.object({
+  version: z.literal(MAP_ROLE_EVIDENCE_VERSION),
+  teamKey: z.string().min(1),
+  mapName: supportedMapNameSchema,
+  side: z.enum(["t", "ct"]),
+  status: mapRoleStatusSchema,
+  confidence: z.number().min(0).max(1),
+  players: z.array(playerMapRoleEvidenceSchema),
+  positionOverlap: z.array(z.object({ positionGroupId: z.string().min(1), playerKeys: z.array(z.string().min(1)).min(2), share: z.number().min(0).max(1) })),
+  positionConcentration: z.number().min(0).max(1).nullable(),
+  unstableCoverage: z.boolean(),
+  representativeRounds: z.array(roleEvidenceLocatorSchema).max(5),
+  basis: z.array(z.string()),
+  limitations: z.array(z.string()),
+});
+
+export const playerMapRoleProfileSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/player-map-role-profile-5.0"),
+  playerKey: z.string().min(1),
+  teamKey: z.string().min(1),
+  declaredRoles: z.array(mainRoleDeclarationSchema),
+  declaredWeaponDuties: z.array(weaponDutyDeclarationSchema),
+  inferredPrimaryRole: inferredMapRoleSchema.nullable(),
+  runnerUpRole: inferredMapRoleSchema.nullable(),
+  separationMargin: z.number().min(0).max(1).nullable(),
+  roleEvidenceScores: z.object({ awper: z.number().min(0).max(1), anchor: z.number().min(0).max(1), opener: z.number().min(0).max(1), closer: z.number().min(0).max(1) }),
+  headlineRole: z.union([inferredMapRoleSchema, z.literal("IGL"), z.literal("IGL / AWPer")]).nullable(),
+  status: mapRoleStatusSchema,
+  confidence: z.number().min(0).max(1),
+  weaponDuty: weaponDutySchema.nullable(),
+  positionGroupDisplay: z.array(z.object({
+    mapName: supportedMapNameSchema,
+    side: z.enum(["t", "ct"]),
+    positionGroupId: z.string().min(1),
+    displayName: z.string().min(1),
+    officialName: z.string().nullable(),
+    resolved: z.boolean(),
+  })),
+  roleAlignments: z.array(z.object({
+    declaration: mainRoleDeclarationSchema,
+    declaredPrimary: declaredRoleSchema.nullable(),
+    declaredSecondary: z.array(declaredRoleSchema),
+    inferredPrimary: inferredMapRoleSchema.nullable(),
+    overall: z.enum(["aligned", "partially_aligned", "different_observation", "not_comparable"]),
+    tSide: z.string(),
+    ctSide: z.string(),
+    disagreementReasons: z.array(z.string()),
+    sampleLimitations: z.array(z.string()),
+  })),
+  weaponDutyAlignments: z.array(z.object({
+    declaration: weaponDutyDeclarationSchema,
+    observedWeaponDuty: weaponDutySchema.nullable(),
+    overall: z.enum(["aligned", "different_observation", "not_comparable"]),
+    sampleLimitations: z.array(z.string()),
+  })),
+  perMapEvidence: z.array(playerMapRoleEvidenceSchema),
+  evidence: z.array(evidenceRefSchema),
+  basis: z.array(z.string()),
+  limitations: z.array(z.string()),
+});
+
+export const teamMapRoleMatrixSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/team-map-role-matrix-4.0"),
+  teamKey: z.string().min(1),
+  mapName: supportedMapNameSchema,
+  side: z.enum(["t", "ct"]),
+  status: mapRoleStatusSchema,
+  confidence: z.number().min(0).max(1),
+  players: z.array(z.object({
+    playerKey: z.string().min(1),
+    primaryPositionGroups: z.array(mapPositionGroupEvidenceSchema.extend({ displayName: z.string().min(1), officialName: z.string().nullable(), resolved: z.boolean() })),
+    responsibility: teamResponsibilitySchema,
+    modifiers: z.array(roleModifierSchema),
+    sampleRounds: z.number().int().nonnegative(),
+    confidence: z.number().min(0).max(1),
+    weaponDuty: weaponDutySchema.nullable(),
+    evidence: z.array(evidenceRefSchema),
+  })),
+  positionOverlap: teamMapResponsibilityEvidenceSchema.shape.positionOverlap,
+  positionConcentration: z.number().min(0).max(1).nullable(),
+  unstableCoverage: z.boolean(),
+  representativeRounds: z.array(evidenceRefSchema),
+  basis: z.array(z.string()),
+  limitations: z.array(z.string()),
+});
+
+const countBreakdownSchema = z.object({ key: z.string().min(1), rounds: z.number().int().nonnegative() });
+export const doubleAwpAnalysisSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/double-awp-analysis-2.0"),
+  teamKey: z.string().min(1),
+  side: z.enum(["t", "ct"]),
+  status: mapRoleStatusSchema,
+  qualifiedRoundCount: z.number().int().nonnegative(),
+  doubleAwpRoundCount: z.number().int().nonnegative(),
+  eligibleRoundShare: z.number().min(0).max(1).nullable(),
+  combinations: z.array(z.object({ playerKeys: z.array(z.string().min(1)).min(2), rounds: z.number().int().positive() })),
+  mapDistribution: z.array(countBreakdownSchema),
+  scorePhaseDistribution: z.array(countBreakdownSchema),
+  economyDistribution: z.array(countBreakdownSchema),
+  opponentEconomyDistribution: z.array(countBreakdownSchema),
+  wins: z.number().int().nonnegative(),
+  winRate: z.number().min(0).max(1).nullable(),
+  openingKills: z.number().int().nonnegative(),
+  openingDeaths: z.number().int().nonnegative(),
+  roundStartAwpOwnerships: z.number().int().nonnegative(),
+  activeAwpSeconds: z.number().nonnegative().nullable(),
+  doubleAwpActiveSeconds: z.number().nonnegative().nullable(),
+  awpKills: z.number().int().nonnegative().nullable(),
+  awpDamage: z.number().nonnegative().nullable(),
+  evidence: z.array(evidenceRefSchema),
+  basis: z.array(z.string()),
+  limitations: z.array(z.string()),
+});
+
+export const playerMapPoolRowSchema = z.object({
+  mapName: supportedMapNameSchema,
+  matchCount: z.number().int().nonnegative(), roundCount: z.number().int().nonnegative(), wins: z.number().int().nonnegative(), losses: z.number().int().nonnegative(), winRate: z.number().min(0).max(1).nullable(),
+  rr: z.number().nonnegative().nullable(), adr: z.number().nonnegative().nullable(), kast: z.number().min(0).max(100).nullable(),
+  openingKills: z.number().int().nonnegative(), openingDeaths: z.number().int().nonnegative(),
+  mainWeapon: z.string().nullable(), globalWeaponDuty: weaponDutySchema.nullable(), mapSideAwpUsage: z.array(z.object({ side: z.enum(["t", "ct"]), duty: weaponDutySchema, qualifiedRounds: z.number().int().nonnegative(), activeSeconds: z.number().nonnegative().nullable() })),
+  tPositionGroup: z.string().nullable(), ctPositionGroup: z.string().nullable(), tResponsibility: teamResponsibilitySchema, ctResponsibility: teamResponsibilitySchema,
+  sampleQuality: z.number().min(0).max(1), confidence: z.number().min(0).max(1), evidence: z.array(evidenceRefSchema),
+});
+
+export type SupportedMapName = z.infer<typeof supportedMapNameSchema>;
+export type MapRoleStatus = z.infer<typeof mapRoleStatusSchema>;
+export type InferredMapRole = z.infer<typeof inferredMapRoleSchema>;
+export type DeclaredRole = z.infer<typeof declaredRoleSchema>;
+export type WeaponDuty = z.infer<typeof weaponDutySchema>;
+export type TeamResponsibility = z.infer<typeof teamResponsibilitySchema>;
+export type RoleModifier = z.infer<typeof roleModifierSchema>;
+export type TResponsibilityResearchCandidate = z.infer<typeof tResponsibilityResearchCandidateSchema>;
+export type TResponsibilityResearchFeatures = z.infer<typeof tResponsibilityResearchFeaturesSchema>;
+export type TResponsibilityResearchProjection = z.infer<typeof tResponsibilityResearchProjectionSchema>;
+export type RoleDeclaration = z.infer<typeof roleDeclarationSchema>;
+export type MainRoleDeclaration = z.infer<typeof mainRoleDeclarationSchema>;
+export type WeaponDutyDeclaration = z.infer<typeof weaponDutyDeclarationSchema>;
+export type RoleEvidenceLocator = z.infer<typeof roleEvidenceLocatorSchema>;
+export type PlayerMapRoleEvidence = z.infer<typeof playerMapRoleEvidenceSchema>;
+export type TeamMapResponsibilityEvidence = z.infer<typeof teamMapResponsibilityEvidenceSchema>;
+export type PlayerMapRoleProfile = z.infer<typeof playerMapRoleProfileSchema>;
+export type TeamMapRoleMatrix = z.infer<typeof teamMapRoleMatrixSchema>;
+export type DoubleAwpAnalysis = z.infer<typeof doubleAwpAnalysisSchema>;
+export type PlayerMapPoolRow = z.infer<typeof playerMapPoolRowSchema>;