@cs2dak/core 0.2.1 → 2.0.0

package/src/map-intelligence/ct-rotation.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+import { FLAG_ALIVE, type DemoPackage } from "@cs2dak/contract";
+import type { ReplayRoundContext, ReplayRoundTrack } from "../tactics/replay-round-context.js";
+import { extractCtRotationRoundFacts } from "./ct-rotation.js";
+import { buildRoundSpatialFrames } from "./spatial.js";
+
+const frameCount = 71;
+const placeDict = ["BombsiteA", "CTSpawn", "BombsiteB", "TRamp", "Apartments"];
+const round = {
+  roundNumber: 1,
+  freezeEndTick: 100,
+  endTick: 800,
+  teamASide: "ct",
+  teamBSide: "t",
+} as DemoPackage["rounds"][number];
+
+function track(
+  playerIndex: number,
+  teamKey: "teamA" | "teamB",
+  side: "ct" | "t",
+  places: number[],
+  flags = Array(frameCount).fill(FLAG_ALIVE),
+): ReplayRoundTrack {
+  return {
+    playerIndex,
+    teamKey,
+    side,
+    steamId64: `7656119800000000${playerIndex + 1}`,
+    x: Array(frameCount).fill(playerIndex * 100),
+    y: Array(frameCount).fill(0),
+    z: Array(frameCount).fill(0),
+    flags,
+    place: places,
+    weapon: Array(frameCount).fill(-1),
+  };
+}
+
+function scenario(options: { deathTick?: number; otherContactTick?: number; secondRotates?: boolean; deathWithoutEnemyContact?: boolean } = {}) {
+  const deathTick = options.deathTick ?? null;
+  const otherContactTick = options.otherContactTick ?? 305;
+  const rotatingFlags = Array(frameCount).fill(FLAG_ALIVE);
+  if (deathTick != null) rotatingFlags.fill(0, Math.floor((deathTick - 100) / 10) + 1);
+  const rotatingPlaces = Array.from({ length: frameCount }, (_, index) => index <= 20 ? 0 : index < 30 ? 1 : 2);
+  const otherContactFrame = Math.round((otherContactTick - 100) / 10);
+  const context: ReplayRoundContext = {
+    round,
+    startTick: 100,
+    tickStep: 10,
+    frameCount,
+    placeDict,
+    weaponDict: [],
+    tracks: [
+      track(0, "teamA", "ct", rotatingPlaces, rotatingFlags),
+      track(1, "teamA", "ct", options.secondRotates ? rotatingPlaces : Array(frameCount).fill(0)),
+      track(2, "teamB", "t", Array.from({ length: frameCount }, (_, index) => index < otherContactFrame ? 3 : 4)),
+    ],
+  };
+  const pkg = {
+    match: { mapName: "de_mirage", tickrate: 10 },
+    rounds: [round],
+    players: [
+      { steamId64: "76561198000000001", teamKey: "teamA" },
+      { steamId64: "76561198000000002", teamKey: "teamA" },
+      { steamId64: "76561198000000003", teamKey: "teamB" },
+    ],
+    damages: [
+      { roundNumber: 1, tick: 250, attackerIndex: 2, victimIndex: 0, healthDamageRaw: 10 },
+      { roundNumber: 1, tick: otherContactTick, attackerIndex: 2, victimIndex: 0, healthDamageRaw: 10 },
+    ],
+    kills: deathTick == null ? [] : [{ roundNumber: 1, tick: deathTick, killerIndex: options.deathWithoutEnemyContact ? null : 2, victimIndex: 0 }],
+    shots: undefined,
+  } as unknown as DemoPackage;
+  const frames = buildRoundSpatialFrames(context, null, null);
+  return extractCtRotationRoundFacts(pkg, "m1", context, round, frames, null, false);
+}
+
+describe("extractCtRotationRoundFacts", () => {
+  it("records a stable cross-area response and its team-relative order without emitting a role", () => {
+    const row = scenario().find((candidate) => candidate.playerIndex === 0)!;
+
+    expect(row).toMatchObject({
+      initialPositionGroupId: "a_site",
+      initialRegion: "a",
+      initialPositionGroupShare: 1,
+      initialResponsibilityResolved: true,
+      firstOwnAreaContactTick: 250,
+      firstOtherAreaContactTick: 305,
+      firstTeamContactTick: 250,
+      leftInitialPositionGroupTick: 310,
+      leaveDelayAfterFirstOtherAreaContactSeconds: 0.5,
+      firstStableDestinationPositionGroupId: "b_site",
+      firstStableDestinationRegion: "b",
+      crossedResponsibilityArea: true,
+      returnedToInitialPositionGroup: false,
+      transitToStableDestinationSeconds: 9,
+      crossAreaDepartureOrder: 1,
+      firstCrossAreaDeparture: true,
+      priorCrossAreaDeparturesAlive: 0,
+      initialAreaStillCovered: true,
+      censoredByDeath: false,
+    });
+    expect(row).not.toHaveProperty("role");
+  });
+
+  it("keeps an unfinished response unknown when death truncates observation", () => {
+    const row = scenario({ deathTick: 330 }).find((candidate) => candidate.playerIndex === 0)!;
+
+    expect(row.deathTick).toBe(330);
+    expect(row.censoredByDeath).toBe(true);
+    expect(row.leftInitialPositionGroupTick).toBeNull();
+    expect(row.firstStableDestinationPositionGroupId).toBeNull();
+    expect(row.crossedResponsibilityArea).toBeNull();
+    expect(row.crossAreaDepartureOrder).toBeNull();
+  });
+
+  it("records an observed full-round stay as false rather than unknown", () => {
+    const row = scenario().find((candidate) => candidate.playerIndex === 1)!;
+
+    expect(row.initialResponsibilityResolved).toBe(true);
+    expect(row.deathTick).toBeNull();
+    expect(row.censoredByDeath).toBe(false);
+    expect(row.crossedResponsibilityArea).toBe(false);
+  });
+
+  it("uses signed contact delay instead of hiding a departure that came first", () => {
+    const row = scenario({ otherContactTick: 350 }).find((candidate) => candidate.playerIndex === 0)!;
+
+    expect(row.leftInitialPositionGroupTick).toBe(310);
+    expect(row.firstOtherAreaContactTick).toBe(350);
+    expect(row.leaveDelayAfterFirstOtherAreaContactSeconds).toBe(-4);
+  });
+
+  it("clips team contacts to the player's observable lifetime", () => {
+    const row = scenario({ deathTick: 190, deathWithoutEnemyContact: true }).find((candidate) => candidate.playerIndex === 0)!;
+
+    expect(row.censoredByDeath).toBe(true);
+    expect(row.firstTeamContactTick).toBeNull();
+    expect(row.firstOwnAreaContactTick).toBeNull();
+    expect(row.firstOtherAreaContactTick).toBeNull();
+  });
+
+  it("preserves simultaneous departures as deterministic shared ranks", () => {
+    const rows = scenario({ secondRotates: true }).filter((candidate) => candidate.playerIndex < 2);
+
+    expect(rows.map((row) => row.crossAreaDepartureOrder)).toEqual([1, 1]);
+    expect(rows.map((row) => row.firstCrossAreaDeparture)).toEqual([true, true]);
+    expect(rows.map((row) => row.priorCrossAreaDeparturesAlive)).toEqual([0, 0]);
+  });
+});

package/src/map-intelligence/ct-rotation.ts

@@ -0,0 +1,324 @@
+import {
+  CT_ROTATION_FACT_VERSION,
+  MAP_INTELLIGENCE_FACT_VERSION,
+  type CtRotationAvailability,
+  type CtRotationRoundFact,
+  type DemoPackage,
+} from "@cs2dak/contract";
+import { getPrimaryCalloutRegion, positionGroupOf, type CalloutGrid, type TacticalRegion } from "@cs2dak/maps";
+import {
+  replayCalloutAt,
+  type ReplayRoundContext,
+  type ReplayRoundTrack,
+} from "../tactics/replay-round-context.js";
+import { openingResponsibilityWindow } from "./opening-window.js";
+import { rounded, type SpatialPlayerSample, type TeamSpatialFrame } from "./spatial.js";
+
+export const CT_ROTATION_RESPONSE_PERSISTENCE_SECONDS = 2;
+
+interface ContactEvent {
+  tick: number;
+  region: TacticalRegion;
+}
+
+interface ResponseObservation {
+  leftTick: number;
+  targetGroup: string;
+  targetRegion: TacticalRegion | null;
+  pathSeconds: number;
+  initialAreaStillCovered: boolean | null;
+  returned: boolean | null;
+  resolvedTick: number;
+}
+
+function availability(
+  pkg: DemoPackage,
+  context: ReplayRoundContext | null,
+  track: ReplayRoundTrack | null,
+  grid: CalloutGrid | null,
+  hasNav: boolean,
+): CtRotationAvailability {
+  const replay = context && track ? "available" : context ? "degraded" : "missing";
+  const combatSources = Number(Boolean(pkg.manifest?.files?.damages)) + Number(Boolean(pkg.manifest?.files?.kills));
+  return {
+    replay,
+    nav: hasNav ? "available" : "missing",
+    callouts: context && (context.placeDict.length > 0 || grid) ? "available" : context ? "degraded" : "missing",
+    shots: pkg.shots ? "available" : "missing",
+    combatTimeline: combatSources === 2 ? "available" : combatSources === 1 ? "degraded" : "missing",
+  };
+}
+
+function frameIndexForTick(context: ReplayRoundContext, tick: number): number {
+  return Math.max(0, Math.min(context.frameCount - 1, Math.round((tick - context.startTick) / context.tickStep)));
+}
+
+function sideOf(pkg: DemoPackage, round: DemoPackage["rounds"][number], playerIndex: number): "t" | "ct" | null {
+  const teamKey = pkg.players[playerIndex]?.teamKey;
+  return teamKey === "teamA" ? round.teamASide : teamKey === "teamB" ? round.teamBSide : null;
+}
+
+function regionAt(
+  pkg: DemoPackage,
+  context: ReplayRoundContext,
+  grid: CalloutGrid | null,
+  playerIndex: number,
+  tick: number,
+): TacticalRegion | null {
+  const track = context.tracks.find((row) => row.playerIndex === playerIndex);
+  if (!track) return null;
+  const callout = replayCalloutAt(context, track, frameIndexForTick(context, tick), grid);
+  return callout ? getPrimaryCalloutRegion(pkg.match.mapName, callout) : null;
+}
+
+function contactEvents(
+  pkg: DemoPackage,
+  context: ReplayRoundContext,
+  round: DemoPackage["rounds"][number],
+  grid: CalloutGrid | null,
+): ContactEvent[] {
+  const result: ContactEvent[] = [];
+  const add = (tick: number, first: number | null, second: number) => {
+    if (first == null || pkg.players[first]?.teamKey === pkg.players[second]?.teamKey) return;
+    const tPlayer = sideOf(pkg, round, first) === "t" ? first : sideOf(pkg, round, second) === "t" ? second : null;
+    const fallback = sideOf(pkg, round, first) === "ct" ? first : second;
+    const region = tPlayer == null ? null : regionAt(pkg, context, grid, tPlayer, tick) ?? regionAt(pkg, context, grid, fallback, tick);
+    if (region) result.push({ tick, region });
+  };
+  for (const damage of pkg.damages) {
+    if (damage.roundNumber === round.roundNumber && damage.healthDamageRaw > 0) add(damage.tick, damage.attackerIndex, damage.victimIndex);
+  }
+  for (const kill of pkg.kills) {
+    if (kill.roundNumber === round.roundNumber) add(kill.tick, kill.killerIndex, kill.victimIndex);
+  }
+  return result.sort((a, b) => a.tick - b.tick);
+}
+
+function groupAndRegion(mapName: string, sample: SpatialPlayerSample): { group: string | null; region: TacticalRegion | null } {
+  return {
+    group: sample.callout ? positionGroupOf(mapName, "ct", sample.callout) : null,
+    region: sample.callout ? getPrimaryCalloutRegion(mapName, sample.callout) : null,
+  };
+}
+
+function stableGroupAt(
+  frames: readonly TeamSpatialFrame[],
+  startIndex: number,
+  playerIndex: number,
+  mapName: string,
+  frameSeconds: number,
+): { group: string; region: TacticalRegion | null; resolvedTick: number } | null {
+  const firstSample = frames[startIndex]?.players.find((row) => row.playerIndex === playerIndex);
+  if (!firstSample) return null;
+  const first = groupAndRegion(mapName, firstSample);
+  if (!first.group) return null;
+  const group = first.group;
+  let seconds = 0;
+  let resolvedTick = frames[startIndex]!.tick;
+  for (let index = startIndex; index < frames.length; index += 1) {
+    const sample = frames[index]!.players.find((row) => row.playerIndex === playerIndex);
+    if (!sample || groupAndRegion(mapName, sample).group !== group) break;
+    seconds += frameSeconds;
+    resolvedTick = frames[index]!.tick;
+    if (seconds >= CT_ROTATION_RESPONSE_PERSISTENCE_SECONDS) return { group, region: first.region, resolvedTick };
+  }
+  return null;
+}
+
+function areaCovered(
+  frame: TeamSpatialFrame | undefined,
+  playerIndex: number,
+  mapName: string,
+  initialRegion: TacticalRegion | null,
+): boolean | null {
+  if (!frame || !initialRegion) return null;
+  const resolved = frame.players
+    .filter((row) => row.playerIndex !== playerIndex)
+    .map((row) => groupAndRegion(mapName, row).region)
+    .filter((region): region is TacticalRegion => region != null);
+  return resolved.includes(initialRegion);
+}
+
+function responseObservation(
+  frames: readonly TeamSpatialFrame[],
+  playerIndex: number,
+  mapName: string,
+  initialGroup: string,
+  initialRegion: TacticalRegion | null,
+  openingEndTick: number,
+  deathTick: number | null,
+  tickrate: number,
+  tickStep: number,
+): ResponseObservation | null {
+  const frameSeconds = tickStep / tickrate;
+  let departureTick: number | null = null;
+  for (let index = 0; index < frames.length; index += 1) {
+    const frame = frames[index]!;
+    if (frame.tick < openingEndTick) continue;
+    const sample = frame.players.find((row) => row.playerIndex === playerIndex);
+    if (!sample) continue;
+    const location = groupAndRegion(mapName, sample);
+    if (location.group === initialGroup) {
+      departureTick = null;
+      continue;
+    }
+    departureTick ??= frame.tick;
+    const target = stableGroupAt(frames, index, playerIndex, mapName, frameSeconds);
+    if (!target || target.group === initialGroup) continue;
+    const returnStart = frames.findIndex((candidate, candidateIndex) => {
+      if (candidateIndex <= index || candidate.tick <= target.resolvedTick) return false;
+      const candidateSample = candidate.players.find((row) => row.playerIndex === playerIndex);
+      return candidateSample != null && groupAndRegion(mapName, candidateSample).group === initialGroup;
+    });
+    let returned: boolean | null = null;
+    if (returnStart >= 0 && stableGroupAt(frames, returnStart, playerIndex, mapName, frameSeconds)?.group === initialGroup) returned = true;
+    else if (deathTick == null) returned = false;
+    return {
+      leftTick: departureTick,
+      targetGroup: target.group,
+      targetRegion: target.region,
+      pathSeconds: Math.max(0, (frame.tick - departureTick) / tickrate),
+      initialAreaStillCovered: areaCovered(frames.find((candidate) => candidate.tick === departureTick), playerIndex, mapName, initialRegion),
+      returned,
+      resolvedTick: target.resolvedTick,
+    };
+  }
+  return null;
+}
+
+export function extractCtRotationRoundFacts(
+  pkg: DemoPackage,
+  matchId: string,
+  context: ReplayRoundContext | null,
+  round: DemoPackage["rounds"][number],
+  frames: readonly TeamSpatialFrame[],
+  grid: CalloutGrid | null,
+  hasNav: boolean,
+): CtRotationRoundFact[] {
+  const tickrate = pkg.match.tickrate || 64;
+  const teamKey = round.teamASide === "ct" ? "teamA" : "teamB";
+  const ctPlayers = pkg.players.flatMap((player, playerIndex) => player.teamKey === teamKey ? [{ player, playerIndex }] : []);
+  const deaths = new Map(pkg.kills.filter((row) => row.roundNumber === round.roundNumber).map((row) => [row.victimIndex, row.tick]));
+  if (!context) {
+    return ctPlayers.map(({ player, playerIndex }) => ({
+      analysisVersion: MAP_INTELLIGENCE_FACT_VERSION,
+      factVersion: CT_ROTATION_FACT_VERSION,
+      matchId,
+      mapName: pkg.match.mapName,
+      roundNumber: round.roundNumber,
+      teamKey,
+      side: "ct",
+      playerIndex,
+      steamId64: player.steamId64,
+      initialPositionGroupId: null,
+      initialRegion: null,
+      initialPositionGroupShare: null,
+      initialResponsibilityResolved: false,
+      initialWindowEligibleSeconds: null,
+      firstOwnAreaContactTick: null,
+      firstOtherAreaContactTick: null,
+      firstTeamContactTick: null,
+      leftInitialPositionGroupTick: null,
+      leaveDelayAfterFirstOtherAreaContactSeconds: null,
+      firstStableDestinationPositionGroupId: null,
+      firstStableDestinationRegion: null,
+      crossedResponsibilityArea: null,
+      returnedToInitialPositionGroup: null,
+      transitToStableDestinationSeconds: null,
+      crossAreaDepartureOrder: null,
+      firstCrossAreaDeparture: null,
+      priorCrossAreaDeparturesAlive: null,
+      initialAreaStillCovered: null,
+      deathTick: deaths.get(playerIndex) ?? null,
+      censoredByDeath: null,
+      roundEndTick: round.endTick,
+      availability: availability(pkg, null, null, grid, hasNav),
+    }));
+  }
+
+  const contacts = contactEvents(pkg, context, round, grid);
+  const openingWindow = openingResponsibilityWindow(round, tickrate);
+  const teamFrames = frames.filter((frame) => frame.teamKey === teamKey && frame.side === "ct");
+  const frameSeconds = context.tickStep / tickrate;
+  const rows = ctPlayers.map(({ player, playerIndex }): CtRotationRoundFact => {
+    const track = context.tracks.find((row) => row.playerIndex === playerIndex) ?? null;
+    const playerFrames = teamFrames.filter((frame) => frame.players.some((row) => row.playerIndex === playerIndex));
+    const openingFrames = playerFrames.filter((frame) => frame.tick >= openingWindow.startTick && frame.tick < openingWindow.endTick);
+    const groups = new Map<string, number>();
+    const regions = new Map<TacticalRegion, number>();
+    for (const frame of openingFrames) {
+      const sample = frame.players.find((row) => row.playerIndex === playerIndex)!;
+      const location = groupAndRegion(pkg.match.mapName, sample);
+      if (location.group) groups.set(location.group, (groups.get(location.group) ?? 0) + frameSeconds);
+      if (location.region) regions.set(location.region, (regions.get(location.region) ?? 0) + frameSeconds);
+    }
+    const initialGroup = [...groups.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0] ?? null;
+    const initialRegion = [...regions.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0] ?? null;
+    const openingSeconds = track ? openingFrames.length * frameSeconds : null;
+    const deathTick = deaths.get(playerIndex) ?? null;
+    const response = initialGroup == null ? null : responseObservation(
+      teamFrames,
+      playerIndex,
+      pkg.match.mapName,
+      initialGroup[0],
+      initialRegion,
+      openingWindow.endTick,
+      deathTick,
+      tickrate,
+      context.tickStep,
+    );
+    const observableContacts = deathTick == null ? contacts : contacts.filter((contact) => contact.tick <= deathTick);
+    const firstTeamContact = observableContacts[0]?.tick ?? null;
+    const firstOwnContact = initialRegion == null ? null : observableContacts.find((row) => row.region === initialRegion)?.tick ?? null;
+    const firstOtherContact = initialRegion == null ? null : observableContacts.find((row) => row.region !== initialRegion)?.tick ?? null;
+    const crossed = response && initialRegion && response.targetRegion
+      ? response.targetRegion !== initialRegion
+      : response == null && deathTick == null && initialGroup != null && initialRegion != null
+        ? false
+        : null;
+    return {
+      analysisVersion: MAP_INTELLIGENCE_FACT_VERSION,
+      factVersion: CT_ROTATION_FACT_VERSION,
+      matchId,
+      mapName: pkg.match.mapName,
+      roundNumber: round.roundNumber,
+      teamKey,
+      side: "ct",
+      playerIndex,
+      steamId64: player.steamId64,
+      initialPositionGroupId: initialGroup?.[0] ?? null,
+      initialRegion,
+      initialPositionGroupShare: initialGroup == null || openingSeconds == null || openingSeconds === 0 ? null : rounded(initialGroup[1] / openingSeconds),
+      initialResponsibilityResolved: initialGroup != null && initialRegion != null,
+      initialWindowEligibleSeconds: rounded(openingSeconds),
+      firstOwnAreaContactTick: firstOwnContact,
+      firstOtherAreaContactTick: firstOtherContact,
+      firstTeamContactTick: firstTeamContact,
+      leftInitialPositionGroupTick: response?.leftTick ?? null,
+      leaveDelayAfterFirstOtherAreaContactSeconds: response && firstOtherContact != null ? rounded((response.leftTick - firstOtherContact) / tickrate) : null,
+      firstStableDestinationPositionGroupId: response?.targetGroup ?? null,
+      firstStableDestinationRegion: response?.targetRegion ?? null,
+      crossedResponsibilityArea: crossed,
+      returnedToInitialPositionGroup: response?.returned ?? null,
+      transitToStableDestinationSeconds: response == null ? null : rounded(response.pathSeconds),
+      crossAreaDepartureOrder: null,
+      firstCrossAreaDeparture: null,
+      priorCrossAreaDeparturesAlive: null,
+      initialAreaStillCovered: response?.initialAreaStillCovered ?? null,
+      deathTick,
+      censoredByDeath: track == null ? null : deathTick == null ? false : response == null || deathTick <= response.resolvedTick,
+      roundEndTick: round.endTick,
+      availability: availability(pkg, context, track, grid, hasNav),
+    };
+  });
+
+  const crossArea = rows.filter((row) => row.crossedResponsibilityArea === true && row.leftInitialPositionGroupTick != null);
+  for (const row of crossArea) {
+    const earlier = crossArea.filter((candidate) => candidate.leftInitialPositionGroupTick! < row.leftInitialPositionGroupTick!).length;
+    row.priorCrossAreaDeparturesAlive = crossArea.filter((candidate) => candidate.leftInitialPositionGroupTick! < row.leftInitialPositionGroupTick!
+      && (candidate.deathTick == null || candidate.deathTick > row.leftInitialPositionGroupTick!)).length;
+    row.crossAreaDepartureOrder = earlier + 1;
+    row.firstCrossAreaDeparture = earlier === 0;
+  }
+  return rows;
+}

package/src/map-intelligence/index.ts

@@ -0,0 +1,74 @@
+import {
+  MAP_INTELLIGENCE_FACT_VERSION,
+  matchMapIntelligenceFactsSchema,
+  type DemoPackage,
+  type MatchMapIntelligenceFacts,
+} from "@cs2dak/contract";
+import { getMapNav, type CalloutGrid, type CompactNav } from "@cs2dak/maps";
+import { createReplayRoundContexts, type ReplayRoundContext } from "../tactics/replay-round-context.js";
+import { extractTacticalRoundFactsWithContexts, type TacticalRoundFact } from "../tactics/round-facts.js";
+import { extractPlayerPositionRoundFacts } from "./player-position.js";
+import { buildRoundSpatialFrames } from "./spatial.js";
+import { extractTeamShapeRoundFacts } from "./team-shape.js";
+import { extractTeamAwpRoundFacts } from "./team-awp-round.js";
+import { extractCtRotationRoundFacts } from "./ct-rotation.js";
+
+export { MAP_INTELLIGENCE_FACT_VERSION } from "@cs2dak/contract";
+export { OPENING_RESPONSIBILITY_SECONDS } from "./opening-window.js";
+export { CT_ROTATION_FACT_VERSION } from "@cs2dak/contract";
+export { CT_ROTATION_RESPONSE_PERSISTENCE_SECONDS } from "./ct-rotation.js";
+export type { CtRotationRoundFact, MatchMapIntelligenceFacts, PlayerPositionRoundFact, TeamAwpRoundFact, TeamShapeRoundFact } from "@cs2dak/contract";
+
+export interface ExtractMatchMapIntelligenceFactsOptions {
+  matchId: string;
+  calloutGrid?: CalloutGrid | null;
+  nav?: CompactNav | null;
+}
+
+/**
+ * Public compact-facts facade. Contexts exist only for this call and are never returned or persisted.
+ */
+export function extractMatchMapIntelligenceFacts(
+  pkg: DemoPackage,
+  options: ExtractMatchMapIntelligenceFactsOptions,
+): MatchMapIntelligenceFacts {
+  return extractMapIntelligenceWithContexts(pkg, options, createReplayRoundContexts(pkg));
+}
+
+function extractMapIntelligenceWithContexts(
+  pkg: DemoPackage,
+  options: ExtractMatchMapIntelligenceFactsOptions,
+  contexts: ReadonlyMap<number, ReplayRoundContext>,
+): MatchMapIntelligenceFacts {
+  const nav = options.nav === undefined ? getMapNav(pkg.match.mapName) : options.nav;
+  const playerPositionRounds = [];
+  const teamShapeRounds = [];
+  const teamAwpRounds = [];
+  const ctRotationRounds = [];
+  for (const round of pkg.rounds) {
+    const context = contexts.get(round.roundNumber) ?? null;
+    const frames = context ? buildRoundSpatialFrames(context, options.calloutGrid ?? null, nav) : [];
+    const positionRows = extractPlayerPositionRoundFacts(pkg, options.matchId, context, round, frames, options.calloutGrid ?? null, nav != null);
+    playerPositionRounds.push(...positionRows);
+    teamShapeRounds.push(...extractTeamShapeRoundFacts(pkg, options.matchId, context, round, frames, options.calloutGrid ?? null, nav != null));
+    teamAwpRounds.push(...extractTeamAwpRoundFacts(pkg, options.matchId, context, positionRows));
+    ctRotationRounds.push(...extractCtRotationRoundFacts(pkg, options.matchId, context, round, frames, options.calloutGrid ?? null, nav != null));
+  }
+  return matchMapIntelligenceFactsSchema.parse({ analysisVersion: MAP_INTELLIGENCE_FACT_VERSION, matchId: options.matchId, mapName: pkg.match.mapName, playerPositionRounds, teamShapeRounds, teamAwpRounds, ctRotationRounds });
+}
+
+
+/**
+ * Internal replay consumers share delta decoding through this compact public facade.
+ * The returned values are facts only; replay frames and pairwise graphs never escape core.
+ */
+export function extractMatchTacticalAndMapIntelligenceFacts(
+  pkg: DemoPackage,
+  options: ExtractMatchMapIntelligenceFactsOptions,
+): { tacticalRounds: TacticalRoundFact[]; mapIntelligence: MatchMapIntelligenceFacts } {
+  const contexts = createReplayRoundContexts(pkg);
+  return {
+    tacticalRounds: extractTacticalRoundFactsWithContexts(pkg, options, contexts),
+    mapIntelligence: extractMapIntelligenceWithContexts(pkg, options, contexts),
+  };
+}

package/src/map-intelligence/map-intelligence.test.ts

@@ -0,0 +1,62 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { loadDemoPackageFromZip } from "../loader.js";
+import { extractMatchMapIntelligenceFacts } from "./index.js";
+
+async function fixture(name: string) {
+  return loadDemoPackageFromZip(await readFile(fileURLToPath(new URL(`../../../../fixtures/input/${name}`, import.meta.url))));
+}
+
+describe("extractMatchMapIntelligenceFacts", () => {
+  it("derives compact Ancient position and shape facts without persisting replay frames", async () => {
+    const pkg = await fixture("sample-2026-05-17_de_ancient_Team_Spirit_13-10_Team_Falcons.zip");
+    const facts = extractMatchMapIntelligenceFacts(pkg, { matchId: "ancient" });
+    expect(facts.playerPositionRounds).toHaveLength(pkg.rounds.length * pkg.players.length);
+    expect(facts.teamShapeRounds).toHaveLength(pkg.rounds.length * 2);
+    expect(facts.teamAwpRounds).toHaveLength(pkg.rounds.length * 2);
+    expect(facts.ctRotationRounds).toHaveLength(pkg.rounds.length * pkg.players.length / 2);
+    expect(facts.playerPositionRounds.some((row) => row.positionGroupDwell.length > 0)).toBe(true);
+    expect(facts.playerPositionRounds.some((row) => row.openingPositionGroupDwell.length > 0)).toBe(true);
+    expect(facts.playerPositionRounds.every((row) => row.openingEligibleSeconds == null || row.eligibleSeconds == null || row.openingEligibleSeconds <= row.eligibleSeconds)).toBe(true);
+    expect(facts.teamShapeRounds.some((row) => row.windows.some((window) => /^\d+(\+\d+)*$/.test(window.partition)))).toBe(true);
+    expect(facts.teamShapeRounds.some((row) => row.openingWindows.length > 0)).toBe(true);
+    expect(facts.ctRotationRounds.some((row) => row.initialResponsibilityResolved)).toBe(true);
+    expect(facts.ctRotationRounds.every((row) => row.side === "ct" && !("role" in row))).toBe(true);
+    expect(extractMatchMapIntelligenceFacts(pkg, { matchId: "ancient" }).ctRotationRounds).toEqual(facts.ctRotationRounds);
+    const serialized = JSON.stringify(facts);
+    expect(serialized).not.toContain('"frameCount"');
+    expect(serialized).not.toContain('"pairwise"');
+  });
+
+  it("keeps Nuke fixture output compact and maps no sniper other than exact AWP into AWP facts", async () => {
+    const pkg = await fixture("sample-2026-02-09_de_nuke_FURIA_2-13_Team_Vitality.zip");
+    const facts = extractMatchMapIntelligenceFacts(pkg, { matchId: "nuke" });
+    expect(facts.mapName).toBe("de_nuke");
+    expect(facts.playerPositionRounds.every((row) => row.awpShots == null || row.awpShots >= 0)).toBe(true);
+    expect(facts.teamShapeRounds.every((row) => row.availability.nav === "available")).toBe(true);
+  });
+
+  it.each([
+    "sample-2026-02-09_de_inferno_Team_Vitality_13-8_FURIA.zip",
+    "sample-2026-02-09_de_overpass_Team_Vitality_13-10_FURIA.zip",
+  ])("retains opening path and multi-route position evidence for %s", async (name) => {
+    const pkg = await fixture(name);
+    const facts = extractMatchMapIntelligenceFacts(pkg, { matchId: name });
+    expect(facts.playerPositionRounds.some((row) => row.openingPath.length > 1)).toBe(true);
+    expect(new Set(facts.playerPositionRounds.flatMap((row) => row.openingPositionGroupDwell.map((group) => group.positionGroupId))).size).toBeGreaterThan(1);
+  });
+
+  it("uses explicit missing/unknown state when replay is unavailable and degrades Anubis without nav", async () => {
+    const pkg = await fixture("sample-2026-05-17_de_ancient_Team_Spirit_13-10_Team_Falcons.zip");
+    const noReplay = { ...pkg, replay: undefined };
+    const missing = extractMatchMapIntelligenceFacts(noReplay, { matchId: "missing" });
+    expect(missing.playerPositionRounds.every((row) => row.openingEligibleSeconds === null && row.eligibleSeconds === null && row.activeAwpSeconds === null && row.availability.replay === "missing")).toBe(true);
+    expect(missing.teamShapeRounds.every((row) => row.openingWindows.length === 0 && row.windows.length === 0 && row.coverageSeconds === null)).toBe(true);
+    expect(missing.teamAwpRounds.every((row) => row.awpActiveSeconds === null && row.availability.replay === "missing")).toBe(true);
+    expect(missing.ctRotationRounds.every((row) => row.initialPositionGroupId === null && row.crossedResponsibilityArea === null && row.availability.replay === "missing")).toBe(true);
+
+    const anubis = extractMatchMapIntelligenceFacts({ ...pkg, match: { ...pkg.match, mapName: "de_anubis" } }, { matchId: "anubis", nav: null });
+    expect(anubis.teamShapeRounds.every((row) => row.availability.nav === "missing")).toBe(true);
+  });
+});

package/src/map-intelligence/opening-window.ts

@@ -0,0 +1,19 @@
+import { OPENING_RESPONSIBILITY_WINDOW_VERSION, type ResponsibilityWindow } from "@cs2dak/contract";
+
+/**
+ * Default-position/responsibility evidence ends before normal mid-round rotations dominate.
+ * Bump the public window version whenever this duration or anchoring semantics change.
+ */
+export const OPENING_RESPONSIBILITY_SECONDS = 20;
+
+export function openingResponsibilityWindow(
+  round: { freezeEndTick: number; endTick: number },
+  tickrate: number,
+): ResponsibilityWindow {
+  return {
+    version: OPENING_RESPONSIBILITY_WINDOW_VERSION,
+    startTick: round.freezeEndTick,
+    endTick: Math.min(round.endTick, round.freezeEndTick + Math.round(OPENING_RESPONSIBILITY_SECONDS * (tickrate || 64))),
+    configuredSeconds: OPENING_RESPONSIBILITY_SECONDS,
+  };
+}

package/src/map-intelligence/player-position.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import type { TeamSpatialFrame } from "./spatial.js";
+import { detectDelayedConvergences } from "./player-position.js";
+
+function frame(tick: number, components: number[][]): TeamSpatialFrame {
+  return {
+    tick, teamKey: "teamA", side: "t", components,
+    players: components.flat().map((playerIndex) => ({ playerIndex, track: {} as never, point: { x: playerIndex, y: 0, z: 0 }, callout: null, navAreaId: null })),
+  };
+}
+
+describe("delayed convergence", () => {
+  it("requires prior isolation, a pre-existing stable group and persistent convergence", () => {
+    const frames = [
+      frame(0, [[1, 2, 3], [0]]), frame(1, [[1, 2, 3], [0]]),
+      frame(2, [[0, 1, 2, 3]]), frame(3, [[0, 1, 2, 3]]),
+    ];
+    expect(detectDelayedConvergences(frames, 0, 1, 1)).toEqual([{ tick: 2, priorIsolationSeconds: 2, joinedComponentSize: 4, persistenceSeconds: 2 }]);
+  });
+
+  it("rejects a topology change caused by a teammate death", () => {
+    const frames = [
+      frame(0, [[1, 2, 3], [0]]), frame(1, [[1, 2, 3], [0]]),
+      frame(2, [[0, 1, 2]]), frame(3, [[0, 1, 2]]),
+    ];
+    expect(detectDelayedConvergences(frames, 0, 1, 1)).toEqual([]);
+  });
+});