@cs2dak/contract 1.0.0 → 1.1.0

package/src/event-package.ts

@@ -0,0 +1,163 @@
+import { z } from "zod";
+import { seriesVetoSchema } from "./veto.js";
+
+export const eventBracketNodeSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  round: z.number().int().positive(),
+  lane: z.enum(["single", "winner", "loser", "grand"]).default("single"),
+  nextWinNodeId: z.string().nullable().optional(),
+  nextLossNodeId: z.string().nullable().optional(),
+});
+
+export const eventStageSchema = z.object({
+  key: z.string().min(1),
+  name: z.string().min(1),
+  type: z.enum(["round_robin", "swiss", "single_elim", "double_elim", "gsl_group"]),
+  teamCount: z.number().int().positive(),
+  advanceCount: z.number().int().nonnegative().default(0),
+  matchFormat: z.enum(["bo1", "bo3", "bo5"]).optional(),
+  finalFormat: z.enum(["bo3", "bo5"]).optional(),
+  bracketNodes: z.array(eventBracketNodeSchema).optional(),
+});
+
+export const eventTeamSchema = z.object({
+  key: z.string().min(1),
+  name: z.string().min(1),
+  players: z.array(z.object({
+    name: z.string().min(1),
+    steamId64: z.string().nullable().optional(),
+  })).default([]),
+});
+
+export const eventMapSchema = z.object({
+  order: z.number().int().positive(),
+  mapName: z.string().min(1),
+  pickedBy: z.enum(["teamA", "teamB"]).nullable().optional(),
+  teamAStartSide: z.enum(["t", "ct"]).nullable().optional(),
+  scoreA: z.number().int().nonnegative().nullable().optional(),
+  scoreB: z.number().int().nonnegative().nullable().optional(),
+  demoHint: z.object({
+    fileName: z.string().nullable().optional(),
+    sha256: z.string().nullable().optional(),
+  }).nullable().optional(),
+});
+
+export const rawDemoHintSchema = z.object({
+  downloadUrl: z.string().url().nullable().optional(),
+  fileName: z.string().nullable().optional(),
+}).nullable().optional();
+
+export const eventSeriesSchema = z.object({
+  key: z.string().min(1),
+  stage: z.string().nullable().optional(),
+  round: z.number().int().nonnegative().nullable().optional(),
+  entryRound: z.string().nullable().optional(),
+  bracketNodeId: z.string().nullable().optional(),
+  status: z.enum(["scheduled", "in_progress", "finished", "cancelled"]).default("scheduled"),
+  teamARecordBefore: z.string().nullable().optional(),
+  teamBRecordBefore: z.string().nullable().optional(),
+  format: z.enum(["bo1", "bo3", "bo5"]),
+  matchUrl: z.string().url().nullable().optional(), // 该系列来源页（HLTV match 页），展示层可链回
+  rawDemoHint: rawDemoHintSchema, // 可选：打包侧已知的原始 demo 包直链（如 HLTV r2-demos rar）
+  teamAKey: z.string().min(1),
+  teamBKey: z.string().min(1),
+  scoreA: z.number().int().nonnegative().nullable().optional(),
+  scoreB: z.number().int().nonnegative().nullable().optional(),
+  scheduledAt: z.string().datetime().nullable().optional(),
+  completedAt: z.string().datetime().nullable().optional(),
+  veto: seriesVetoSchema.nullable().optional(),
+  maps: z.array(eventMapSchema).default([]),
+});
+
+export const eventPackageSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/event-package-1.0"),
+  source: z.enum(["rivalhub", "manual", "r2"]),
+  exportedAt: z.string().datetime(),
+  event: z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.string().min(1),
+    sourceUrl: z.string().url().optional(), // 赛事来源页（如 HLTV results 页），展示层可链回
+    group: z.string().optional(), // 共享归组键：同一赛事按 stage 拆多包时共用，Gallery 折叠
+    stages: z.array(eventStageSchema).default([]),
+  }),
+  teams: z.array(eventTeamSchema),
+  series: z.array(eventSeriesSchema),
+}).superRefine((value, context) => {
+  const teamKeys = new Set(value.teams.map((team) => team.key));
+  const stageKeys = new Set(value.event.stages.map((stage) => stage.key));
+  const seriesKeys = new Set(value.series.map((series) => series.key));
+  if (teamKeys.size !== value.teams.length) context.addIssue({ code: z.ZodIssueCode.custom, path: ["teams"], message: "队伍 key 必须唯一" });
+  if (stageKeys.size !== value.event.stages.length) context.addIssue({ code: z.ZodIssueCode.custom, path: ["event", "stages"], message: "阶段 key 必须唯一" });
+  if (seriesKeys.size !== value.series.length) context.addIssue({ code: z.ZodIssueCode.custom, path: ["series"], message: "系列赛 key 必须唯一" });
+  for (const [stageIndex, stage] of value.event.stages.entries()) {
+    const nodes = stage.bracketNodes ?? [];
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    if (nodeIds.size !== nodes.length) context.addIssue({ code: z.ZodIssueCode.custom, path: ["event", "stages", stageIndex, "bracketNodes"], message: "bracket 节点 id 必须唯一" });
+    for (const [nodeIndex, node] of nodes.entries()) {
+      for (const target of [node.nextWinNodeId, node.nextLossNodeId]) {
+        if (target && !nodeIds.has(target)) context.addIssue({ code: z.ZodIssueCode.custom, path: ["event", "stages", stageIndex, "bracketNodes", nodeIndex], message: "bracket 晋级关系引用了不存在的节点" });
+        const targetNode = target ? nodes.find((candidate) => candidate.id === target) : null;
+        if (targetNode && targetNode.round <= node.round) context.addIssue({ code: z.ZodIssueCode.custom, path: ["event", "stages", stageIndex, "bracketNodes", nodeIndex], message: "bracket 晋级关系必须指向后续轮次" });
+      }
+    }
+    const visiting = new Set<string>();
+    const visited = new Set<string>();
+    const visit = (id: string): boolean => {
+      if (visiting.has(id)) return true;
+      if (visited.has(id)) return false;
+      visiting.add(id);
+      const node = nodes.find((candidate) => candidate.id === id);
+      const cyclic = [node?.nextWinNodeId, node?.nextLossNodeId].some((target) => target ? visit(target) : false);
+      visiting.delete(id);
+      visited.add(id);
+      return cyclic;
+    };
+    if (nodes.some((node) => visit(node.id))) context.addIssue({ code: z.ZodIssueCode.custom, path: ["event", "stages", stageIndex, "bracketNodes"], message: "bracket 晋级关系不能成环" });
+  }
+  for (const [index, series] of value.series.entries()) {
+    if (!teamKeys.has(series.teamAKey) || !teamKeys.has(series.teamBKey)) {
+      context.addIssue({ code: z.ZodIssueCode.custom, path: ["series", index], message: "series 引用了不存在的队伍" });
+    }
+    if (series.stage && !stageKeys.has(series.stage)) {
+      context.addIssue({ code: z.ZodIssueCode.custom, path: ["series", index, "stage"], message: "series 引用了不存在的阶段" });
+    }
+    if (series.bracketNodeId) {
+      const stage = value.event.stages.find((candidate) => candidate.key === series.stage);
+      if (!stage?.bracketNodes?.some((node) => node.id === series.bracketNodeId)) context.addIssue({ code: z.ZodIssueCode.custom, path: ["series", index, "bracketNodeId"], message: "series 引用了不存在的 bracket 节点" });
+    }
+    if (series.teamAKey === series.teamBKey) {
+      context.addIssue({ code: z.ZodIssueCode.custom, path: ["series", index], message: "系列赛双方不能是同一队" });
+    }
+    if (new Set(series.maps.map((map) => map.order)).size !== series.maps.length) {
+      context.addIssue({ code: z.ZodIssueCode.custom, path: ["series", index, "maps"], message: "系列赛地图顺序必须唯一" });
+    }
+  }
+});
+
+export type EventPackage = z.infer<typeof eventPackageSchema>;
+export type EventStage = z.infer<typeof eventStageSchema>;
+export type EventBracketNode = z.infer<typeof eventBracketNodeSchema>;
+export type EventTeam = z.infer<typeof eventTeamSchema>;
+export type EventSeries = z.infer<typeof eventSeriesSchema>;
+export type RawDemoHint = z.infer<typeof rawDemoHintSchema>;
+
+export const eventsManifestSchema = z.object({
+  version: z.literal("cs2-demo-analysis-kit/events-manifest-1.0"),
+  generatedAt: z.string().datetime(),
+  events: z.array(z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    size: z.number().int().nonnegative(),
+    sha256: z.string().regex(/^[a-fA-F0-9]{64}$/),
+    urls: z.array(z.string().url()).min(1),
+    packageVersion: z.string().min(1),
+    // 展示层可选字段（向后兼容；旧 manifest 不带也合法）：
+    description: z.string().optional(), // 卡片副标题文案
+    builtin: z.boolean().optional(), // 首发/内置：进入页面提示一键下载
+    group: z.string().optional(), // UI 归组键（同 group 折叠成一个赛事、展开见各阶段，如 iem-cologne-major-2026）
+  })),
+});
+
+export type EventsManifest = z.infer<typeof eventsManifestSchema>;

package/src/evidence.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+/**
+ * 可定位的分析证据。
+ *
+ * 这是跨 core/cohort/presentation 的纯数据合同；它只说明要看哪一段比赛、
+ * 以及这一段为何与结果有关，不携带 Studio 导航或持久化语义。
+ */
+export const evidenceRoleSchema = z.enum(["example", "supporting", "counterexample"]);
+
+export const evidenceRefSchema = z.object({
+  matchId: z.string().min(1),
+  roundNumber: z.number().int().positive(),
+  tick: z.number().int().positive().optional(),
+  eventKey: z.string().min(1).optional(),
+  areaKey: z.string().min(1).optional(),
+  reason: z.string().min(1),
+  role: evidenceRoleSchema.optional(),
+});
+
+export type EvidenceRole = z.infer<typeof evidenceRoleSchema>;
+export type EvidenceRef = z.infer<typeof evidenceRefSchema>;

package/src/index.ts

@@ -9,3 +9,12 @@ export * from "./player.js";
 export * from "./team.js";
 export * from "./series.js";
 export * from "./workspace.js";
+export * from "./trails.js";
+export * from "./duel.js";
+export * from "./veto.js";
+export * from "./event-package.js";
+export * from "./bracket.js";
+export * from "./radar-field.js";
+export * from "./evidence.js";
+export * from "./map-intelligence.js";
+export * from "./map-role.js";

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>;