Merge wl-CG-0MMLTPXVR0F9K0JS-meta-progression: Implement meta-progression system

Author: Sorra

example-games/main-street/MainStreetCards.ts

@@ -856,11 +856,23 @@ const UPGRADE_TEMPLATES: UpgradeCard[] = [
 /**
  * Creates the full Business deck for a game (each template repeated
  * `copies` times to ensure adequate supply for 20 turns).
+ *
+ * @param copies          Number of copies per template (default 3).
+ * @param unlockedCardIds Optional list of unlocked card IDs for tier filtering.
+ *                        When provided, only templates whose ID is in this list
+ *                        are included. When omitted, the full pool is used.
  */
-export function createBusinessDeck(copies: number = 3): BusinessCard[] {
+export function createBusinessDeck(
+  copies: number = 3,
+  unlockedCardIds?: string[],
+): BusinessCard[] {
+  const templates = unlockedCardIds
+    ? BUSINESS_TEMPLATES.filter((t) => unlockedCardIds.includes(t.id))
+    : BUSINESS_TEMPLATES;
+
   const deck: BusinessCard[] = [];
   for (let c = 0; c < copies; c++) {
-    for (const template of BUSINESS_TEMPLATES) {
+    for (const template of templates) {
       deck.push(makeBusiness({ ...template, id: `${template.id}-${c}` }));
     }
   }
@@ -869,11 +881,23 @@ export function createBusinessDeck(copies: number = 3): BusinessCard[] {
 
 /**
  * Creates the full Event deck for a game.
+ *
+ * @param copies          Number of copies per template (default 3).
+ * @param unlockedCardIds Optional list of unlocked card IDs for tier filtering.
+ *                        When provided, only templates whose ID is in this list
+ *                        are included. When omitted, the full pool is used.
  */
-export function createEventDeck(copies: number = 3): EventCard[] {
+export function createEventDeck(
+  copies: number = 3,
+  unlockedCardIds?: string[],
+): EventCard[] {
+  const templates = unlockedCardIds
+    ? EVENT_TEMPLATES.filter((t) => unlockedCardIds.includes(t.id))
+    : EVENT_TEMPLATES;
+
   const deck: EventCard[] = [];
   for (let c = 0; c < copies; c++) {
-    for (const template of EVENT_TEMPLATES) {
+    for (const template of templates) {
       deck.push({ ...template, id: `${template.id}-${c}` });
     }
   }
@@ -882,11 +906,23 @@ export function createEventDeck(copies: number = 3): EventCard[] {
 
 /**
  * Creates the full Upgrade deck for a game.
+ *
+ * @param copies          Number of copies per template (default 2).
+ * @param unlockedCardIds Optional list of unlocked card IDs for tier filtering.
+ *                        When provided, only templates whose ID is in this list
+ *                        are included. When omitted, the full pool is used.
  */
-export function createUpgradeDeck(copies: number = 2): UpgradeCard[] {
+export function createUpgradeDeck(
+  copies: number = 2,
+  unlockedCardIds?: string[],
+): UpgradeCard[] {
+  const templates = unlockedCardIds
+    ? UPGRADE_TEMPLATES.filter((t) => unlockedCardIds.includes(t.id))
+    : UPGRADE_TEMPLATES;
+
   const deck: UpgradeCard[] = [];
   for (let c = 0; c < copies; c++) {
-    for (const template of UPGRADE_TEMPLATES) {
+    for (const template of templates) {
       deck.push({ ...template, id: `${template.id}-${c}` });
     }
   }

example-games/main-street/MainStreetSaveLoad.ts

@@ -9,9 +9,14 @@ import {
   serializeMainStreetState,
   deserializeMainStreetState,
 } from './MainStreetState';
+import {
+  TIER_DEFINITIONS,
+  ORDERED_TIER_DEFINITIONS,
+  deriveUnlockedCardIds,
+} from './MainStreetTiers';
 
 export const MAIN_STREET_SAVE_SCHEMA_VERSION = 1;
-export const MAIN_STREET_CAMPAIGN_SCHEMA_VERSION = 1;
+export const MAIN_STREET_CAMPAIGN_SCHEMA_VERSION = 2;
 export const MAIN_STREET_GAME_TYPE = 'main-street';
 export const MAIN_STREET_RUN_SLOT = 'turn-start';
 export const MAIN_STREET_CAMPAIGN_SLOT = 'campaign-default';
@@ -31,12 +36,26 @@ export const mainStreetCampaignSerializer: SaveSerializer<
 > = {
   schemaVersion: MAIN_STREET_CAMPAIGN_SCHEMA_VERSION,
   serialize: (state) => structuredClone(state),
-  deserialize: (data) => structuredClone(data),
+  deserialize: (data) => {
+    // v1 -> v2 migration: add schemaVersion, unlockedCardIds, milestoneHistory
+    if (!data.schemaVersion || data.schemaVersion === 1) {
+      return {
+        ...data,
+        schemaVersion: 2,
+        unlockedCardIds: deriveUnlockedCardIds(data.unlockedTiers),
+        milestoneHistory: [],
+      };
+    }
+    return structuredClone(data);
+  },
 };
 
 export function createDefaultCampaignProgress(): MainStreetCampaignProgress {
   return {
+    schemaVersion: MAIN_STREET_CAMPAIGN_SCHEMA_VERSION,
     unlockedTiers: ['tier-1'],
+    unlockedCardIds: TIER_DEFINITIONS['tier-1'].cumulativeCardIds.slice(),
+    milestoneHistory: [],
     persistentReputation: 0,
     highestScore: 0,
     totalRuns: 0,
@@ -45,6 +64,74 @@ export function createDefaultCampaignProgress(): MainStreetCampaignProgress {
   };
 }
 
+/**
+ * Evaluates tier unlocks and updates campaign progress after a completed run.
+ *
+ * Called after EndCheck phase determines the game result.
+ * Mutates the campaign progress in place, then persists it.
+ *
+ * @param campaign  Current campaign progress (loaded from storage).
+ * @param state     Completed game state (after EndCheck).
+ * @param store     Save/Load store for persistence (optional; if provided, saves automatically).
+ * @returns The updated campaign progress.
+ */
+export async function updateCampaignAfterRun(
+  campaign: MainStreetCampaignProgress,
+  state: MainStreetState,
+  store?: SaveLoadStore,
+): Promise<MainStreetCampaignProgress> {
+  const now = new Date().toISOString();
+
+  // Update statistics
+  campaign.totalRuns += 1;
+  if (state.gameResult === 'win') campaign.totalWins += 1;
+  if (state.finalScore > campaign.highestScore) {
+    campaign.highestScore = state.finalScore;
+  }
+  if (state.resourceBank.reputation > campaign.persistentReputation) {
+    campaign.persistentReputation = state.resourceBank.reputation;
+  }
+
+  // Evaluate tier unlocks (ordered by tier number)
+  for (const tierDef of ORDERED_TIER_DEFINITIONS) {
+    // Skip tier-1 (always unlocked) and already-unlocked tiers
+    if (tierDef.id === 'tier-1') continue;
+    if (campaign.unlockedTiers.includes(tierDef.id)) continue;
+
+    const reputationMet =
+      state.resourceBank.reputation >= tierDef.reputationThreshold;
+    const challengeMet = tierDef.challengeCondition(state);
+
+    if (reputationMet || challengeMet) {
+      campaign.unlockedTiers.push(tierDef.id);
+      campaign.milestoneHistory.push({
+        tierId: tierDef.id,
+        triggerType: reputationMet ? 'reputation' : 'challenge',
+        reputationAtUnlock: reputationMet
+          ? state.resourceBank.reputation
+          : null,
+        challengeIdsAtUnlock: challengeMet
+          ? [...state.challengesCompleted]
+          : null,
+        runFinalScore: state.finalScore,
+        runSeed: state.seed,
+        unlockedAt: now,
+      });
+    }
+  }
+
+  // Derive updated card list from all unlocked tiers
+  campaign.unlockedCardIds = deriveUnlockedCardIds(campaign.unlockedTiers);
+  campaign.lastUpdatedAt = now;
+
+  // Persist if store is provided
+  if (store) {
+    await saveCampaignProgress(store, campaign);
+  }
+
+  return campaign;
+}
+
 export async function saveTurnStartCheckpoint(
   store: SaveLoadStore,
   state: MainStreetState,

example-games/main-street/MainStreetState.ts

@@ -214,12 +214,48 @@ export interface MainStreetSerializedState {
   activityLog: LogEntry[];
 }
 
+/** Record of a single milestone (tier unlock) achievement. */
+export interface MilestoneRecord {
+  /** Tier ID that was unlocked, e.g. 'tier-3'. */
+  tierId: string;
+  /** Which trigger path caused the unlock. */
+  triggerType: 'reputation' | 'challenge';
+  /** For reputation triggers: the reputation value at end-of-run. For challenge triggers: null. */
+  reputationAtUnlock: number | null;
+  /** For challenge triggers: the IDs of challenges completed that satisfied the condition. For reputation triggers: null. */
+  challengeIdsAtUnlock: string[] | null;
+  /** The final score of the run that triggered the unlock. */
+  runFinalScore: number;
+  /** The seed of the run that triggered the unlock. */
+  runSeed: string;
+  /** ISO 8601 timestamp when the milestone was achieved. */
+  unlockedAt: string;
+}
+
 export interface MainStreetCampaignProgress {
+  /** Schema version for forward-compatible deserialization. */
+  schemaVersion: number;
+  /** List of unlocked tier IDs, e.g. ['tier-1', 'tier-2']. Always includes 'tier-1'. */
   unlockedTiers: string[];
+  /**
+   * IDs of all cards unlocked via tier progression. Derived from unlockedTiers
+   * at runtime, but persisted for fast lookup and offline validation.
+   */
+  unlockedCardIds: string[];
+  /**
+   * History of milestone achievements. Each entry records when a tier was
+   * unlocked, which trigger path was used, and the run context.
+   */
+  milestoneHistory: MilestoneRecord[];
+  /** Highest single-run reputation achieved across all runs. */
   persistentReputation: number;
+  /** Highest final score achieved across all runs. */
   highestScore: number;
+  /** Total number of completed runs (win or loss). */
   totalRuns: number;
+  /** Total number of winning runs. */
   totalWins: number;
+  /** ISO 8601 timestamp of the last update to this campaign data. */
   lastUpdatedAt: string;
 }
 
@@ -231,6 +267,12 @@ export interface MainStreetSetupOptions {
   seed?: string;
   /** Difficulty preset name. Defaults to 'Medium' if omitted. */
   difficulty?: DifficultyName;
+  /**
+   * Card IDs unlocked via campaign tier progression. When provided, deck builders
+   * filter templates to include only cards whose IDs are in this list. When omitted,
+   * the full card pool is used (non-campaign / backward-compatible mode).
+   */
+  unlockedCardIds?: string[];
 }
 
 // ── Seed Helpers ────────────────────────────────────────────
@@ -302,9 +344,9 @@ export function setupMainStreetGame(options: MainStreetSetupOptions = {}): MainS
   const config = getPreset(options.difficulty);
 
   // Create and shuffle decks
-  const businessDeck = createBusinessDeck();
-  const eventDeck = createEventDeck();
-  const upgradeDeck = createUpgradeDeck();
+  const businessDeck = createBusinessDeck(3, options.unlockedCardIds);
+  const eventDeck = createEventDeck(3, options.unlockedCardIds);
+  const upgradeDeck = createUpgradeDeck(2, options.unlockedCardIds);
 
   shuffleArray(businessDeck, rng);
   shuffleArray(eventDeck, rng);