blacktrigram 0.7.2

package/lib/systems/ai/ArchetypeEnforcer.js

@@ -0,0 +1,279 @@
+import { PlayerArchetype } from "../../types/common.js";
+import "../../types/index.js";
+import { AIActionType } from "./types.js";
+//#region src/systems/ai/ArchetypeEnforcer.ts
+/**
+* Archetype Behavior Enforcement System
+* 
+* Centralizes archetype-specific combat philosophy enforcement to ensure
+* each of the 5 player archetypes has immediately recognizable and distinct
+* AI behavior patterns.
+* 
+* **Korean Philosophy Integration (한국 무술 철학)**:
+* - 무사 (Musa): 명예 (Honor) - Direct, honorable combat
+* - 암살자 (Amsalja): 은밀 (Stealth) - Silent, precise takedowns
+* - 해커 (Hacker): 분석 (Analysis) - Tech-enhanced tactical combat
+* - 정보요원 (Jeongbo): 심리전 (Psychological Warfare) - Strategic manipulation
+* - 조직폭력배 (Jojik): 생존 (Survival) - Ruthless, unpredictable tactics
+* 
+* @module systems/ai/ArchetypeEnforcer
+* @category AI Combat
+* @korean 원형 행동 강화 시스템
+*/
+/**
+* Archetype enforcement rules for all 5 player archetypes
+* 
+* Defines distinct combat philosophies with measurable behavior patterns
+* that make each archetype immediately identifiable through AI actions.
+* 
+* @korean 5대 원형 강화 규칙
+*/
+var ARCHETYPE_ENFORCEMENT = {
+	[PlayerArchetype.MUSA]: {
+		preferredActions: [
+			AIActionType.ATTACK,
+			AIActionType.APPROACH,
+			AIActionType.TECHNIQUE
+		],
+		prohibitedActions: [AIActionType.FEINT],
+		signatureMove: "musa_mountain_breaker",
+		signatureCondition: (context) => {
+			/**
+			* Musa (무사) signature move condition: Mountain Breaker when opponent <40% health
+			* 
+			* NOTE: Uses opponentMaxHealth if available, otherwise assumes symmetric max-health
+			* pools (context.playerMaxHealth === opponentMaxHealth). If asymmetric max health
+			* exists, CombatContext provides opponentMaxHealth for accurate calculation.
+			*/
+			const maxHealth = context.opponentMaxHealth ?? context.playerMaxHealth;
+			if (maxHealth <= 0) return false;
+			return context.opponentHealth / maxHealth < .4;
+		},
+		actionFrequencies: {
+			[AIActionType.ATTACK]: .7,
+			[AIActionType.DEFEND]: .1,
+			[AIActionType.RETREAT]: .02,
+			[AIActionType.APPROACH]: .15,
+			[AIActionType.FEINT]: 0,
+			[AIActionType.TECHNIQUE]: .7,
+			[AIActionType.COUNTER]: .1,
+			[AIActionType.STANCE_CHANGE]: .1,
+			[AIActionType.CIRCLE]: .05,
+			[AIActionType.WAIT]: .03,
+			[AIActionType.COMBO]: .05
+		}
+	},
+	[PlayerArchetype.AMSALJA]: {
+		preferredActions: [
+			AIActionType.TECHNIQUE,
+			AIActionType.CIRCLE,
+			AIActionType.COUNTER
+		],
+		prohibitedActions: [],
+		signatureMove: "amsalja_silent_death",
+		signatureCondition: (context) => {
+			return context.opponentBalance === "VULNERABLE" || context.opponentBalance === "HELPLESS";
+		},
+		actionFrequencies: {
+			[AIActionType.TECHNIQUE]: .6,
+			[AIActionType.CIRCLE]: .2,
+			[AIActionType.ATTACK]: .15,
+			[AIActionType.RETREAT]: .05,
+			[AIActionType.DEFEND]: .1,
+			[AIActionType.APPROACH]: .1,
+			[AIActionType.FEINT]: .1,
+			[AIActionType.COUNTER]: .2,
+			[AIActionType.STANCE_CHANGE]: .15,
+			[AIActionType.WAIT]: .05,
+			[AIActionType.COMBO]: .1
+		}
+	},
+	[PlayerArchetype.HACKER]: {
+		preferredActions: [
+			AIActionType.WAIT,
+			AIActionType.TECHNIQUE,
+			AIActionType.CIRCLE
+		],
+		prohibitedActions: [],
+		signatureMove: "hacker_system_crash",
+		signatureCondition: (context) => {
+			return context.timeInMatch > 2e4;
+		},
+		actionFrequencies: {
+			[AIActionType.WAIT]: .25,
+			[AIActionType.TECHNIQUE]: .4,
+			[AIActionType.CIRCLE]: .15,
+			[AIActionType.ATTACK]: .15,
+			[AIActionType.DEFEND]: .05,
+			[AIActionType.APPROACH]: .05,
+			[AIActionType.RETREAT]: .1,
+			[AIActionType.FEINT]: .05,
+			[AIActionType.COUNTER]: .15,
+			[AIActionType.STANCE_CHANGE]: .1,
+			[AIActionType.COMBO]: .05
+		}
+	},
+	[PlayerArchetype.JEONGBO_YOWON]: {
+		preferredActions: [
+			AIActionType.FEINT,
+			AIActionType.COUNTER,
+			AIActionType.TECHNIQUE
+		],
+		prohibitedActions: [],
+		signatureMove: "jeongbo_precision_takedown",
+		signatureCondition: (context) => {
+			return context.opponentBalance === "HELPLESS";
+		},
+		actionFrequencies: {
+			[AIActionType.FEINT]: .3,
+			[AIActionType.TECHNIQUE]: .35,
+			[AIActionType.COUNTER]: .2,
+			[AIActionType.WAIT]: .1,
+			[AIActionType.ATTACK]: .05,
+			[AIActionType.DEFEND]: .1,
+			[AIActionType.APPROACH]: .1,
+			[AIActionType.RETREAT]: .05,
+			[AIActionType.CIRCLE]: .15,
+			[AIActionType.STANCE_CHANGE]: .1,
+			[AIActionType.COMBO]: .05
+		}
+	},
+	[PlayerArchetype.JOJIK_POKRYEOKBAE]: {
+		preferredActions: [
+			AIActionType.ATTACK,
+			AIActionType.TECHNIQUE,
+			AIActionType.STANCE_CHANGE
+		],
+		prohibitedActions: [],
+		signatureMove: "jojik_improvised_weapon",
+		signatureCondition: (context) => {
+			/**
+			* Jojik (조직폭력배) signature move: Improvised Weapon when desperate (<30% health)
+			* 
+			* This condition uses playerHealth (the AI's health) to trigger desperate tactics.
+			*/
+			const maxHealth = context.playerMaxHealth;
+			if (maxHealth <= 0) return false;
+			return context.playerHealth / maxHealth < .3;
+		},
+		actionFrequencies: {
+			[AIActionType.ATTACK]: .5,
+			[AIActionType.TECHNIQUE]: .25,
+			[AIActionType.STANCE_CHANGE]: .8,
+			[AIActionType.RETREAT]: .05,
+			[AIActionType.FEINT]: .05,
+			[AIActionType.DEFEND]: .1,
+			[AIActionType.APPROACH]: .15,
+			[AIActionType.COUNTER]: .1,
+			[AIActionType.CIRCLE]: .1,
+			[AIActionType.WAIT]: .03,
+			[AIActionType.COMBO]: .1
+		}
+	}
+};
+/**
+* Enforce archetype-specific behavior on AI decision
+* 
+* Applies philosophy-based restrictions and redirects to enforce distinct
+* combat patterns for each archetype. This ensures players can identify
+* which archetype they're fighting based on behavior alone.
+* 
+* **Enforcement Logic**:
+* 1. Check for prohibited actions → Replace with preferred action
+* 2. Check for signature move condition → Override with signature move
+* 3. Return decision (possibly modified)
+* 
+* @korean 원형 행동 강화
+* 
+* @param decision - Original AI decision from DecisionTree
+* @param archetype - Player archetype to enforce
+* @param context - Current combat context
+* @returns Modified decision enforcing archetype philosophy
+*/
+function enforceArchetypeBehavior(decision, archetype, context) {
+	const rules = ARCHETYPE_ENFORCEMENT[archetype];
+	if (rules.prohibitedActions.includes(decision.action)) {
+		if (rules.preferredActions.length === 0) {
+			console.warn(`[ArchetypeEnforcer] ${archetype} has empty preferredActions array. Using original decision with warning.`);
+			return {
+				...decision,
+				reason: `Archetype enforcement: ${archetype} prohibited action ${decision.action}, but no alternatives available`
+			};
+		}
+		const alternativeAction = rules.preferredActions[Math.floor(Math.random() * rules.preferredActions.length)];
+		return {
+			...decision,
+			action: alternativeAction,
+			reason: `Archetype enforcement: ${archetype} does not use ${decision.action} (원형 강화: ${decision.action} 사용 불가)`
+		};
+	}
+	if (rules.signatureCondition(context)) return {
+		action: AIActionType.TECHNIQUE,
+		targetVitalPoint: void 0,
+		priority: 10,
+		reason: `Signature move: ${rules.signatureMove} for ${archetype} (서명 기술: ${rules.signatureMove})`
+	};
+	return decision;
+}
+/**
+* Get signature move ID for archetype
+* 
+* Returns the technique ID of this archetype's signature move.
+* Used for technique selection in useAICombat.ts.
+* 
+* @korean 서명 기술 ID 가져오기
+* 
+* @param archetype - Player archetype
+* @returns Signature technique ID
+*/
+function getSignatureMove(archetype) {
+	return ARCHETYPE_ENFORCEMENT[archetype].signatureMove;
+}
+/**
+* Check if signature move condition is met
+* 
+* Evaluates whether the archetype should execute its signature move
+* based on current combat context.
+* 
+* @korean 서명 기술 조건 확인
+* 
+* @param archetype - Player archetype
+* @param context - Current combat context
+* @returns True if signature move should be executed
+*/
+function shouldExecuteSignatureMove(archetype, context) {
+	return ARCHETYPE_ENFORCEMENT[archetype].signatureCondition(context);
+}
+/**
+* Get action frequency target for archetype
+* 
+* Returns the target frequency (0.0-1.0) for a specific action type
+* based on archetype combat philosophy.
+* 
+* @korean 행동 빈도 목표 가져오기
+* 
+* @param archetype - Player archetype
+* @param actionType - AI action type
+* @returns Target frequency for this action (0.0-1.0)
+*/
+function getActionFrequency(archetype, actionType) {
+	return ARCHETYPE_ENFORCEMENT[archetype].actionFrequencies[actionType] ?? 0;
+}
+/**
+* Check if action is prohibited for archetype
+* 
+* Returns true if the archetype's philosophy prohibits using this action.
+* 
+* @korean 금지된 행동 확인
+* 
+* @param archetype - Player archetype
+* @param actionType - AI action type to check
+* @returns True if action is prohibited
+*/
+function isActionProhibited(archetype, actionType) {
+	return ARCHETYPE_ENFORCEMENT[archetype].prohibitedActions.includes(actionType);
+}
+//#endregion
+export { ARCHETYPE_ENFORCEMENT, enforceArchetypeBehavior, getActionFrequency, getSignatureMove, isActionProhibited, shouldExecuteSignatureMove };
+
+//# sourceMappingURL=ArchetypeEnforcer.js.map

package/lib/systems/ai/ArchetypeEnforcer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArchetypeEnforcer.js","names":[],"sources":["../../../src/systems/ai/ArchetypeEnforcer.ts"],"sourcesContent":["/**\n * Archetype Behavior Enforcement System\n * \n * Centralizes archetype-specific combat philosophy enforcement to ensure\n * each of the 5 player archetypes has immediately recognizable and distinct\n * AI behavior patterns.\n * \n * **Korean Philosophy Integration (한국 무술 철학)**:\n * - 무사 (Musa): 명예 (Honor) - Direct, honorable combat\n * - 암살자 (Amsalja): 은밀 (Stealth) - Silent, precise takedowns\n * - 해커 (Hacker): 분석 (Analysis) - Tech-enhanced tactical combat\n * - 정보요원 (Jeongbo): 심리전 (Psychological Warfare) - Strategic manipulation\n * - 조직폭력배 (Jojik): 생존 (Survival) - Ruthless, unpredictable tactics\n * \n * @module systems/ai/ArchetypeEnforcer\n * @category AI Combat\n * @korean 원형 행동 강화 시스템\n */\n\nimport { PlayerArchetype } from \"@/types\";\nimport { AIDecision, AIActionType, CombatContext } from \"./types\";\n\n/**\n * Archetype enforcement rules defining distinct combat behaviors\n * \n * Each archetype has:\n * - Preferred actions (used most frequently)\n * - Prohibited actions (never used due to philosophy)\n * - Signature move (iconic technique with specific trigger condition)\n * - Action frequencies (target distribution percentages)\n * \n * **Note on Action Frequencies**:\n * These values represent **target frequencies/proportions** for each action type\n * rather than a single normalized probability distribution. Multiple actions can have\n * high target frequencies because they can occur in overlapping situations:\n * - ATTACK (70%) and TECHNIQUE (70%) both represent aggressive behavior\n * - STANCE_CHANGE (80%) occurs frequently but doesn't prevent other actions\n * - The frequencies serve as **behavioral targets** to guide AI personality,\n *   and are not required to sum to 100% across all actions\n * \n * @korean 원형 강화 규칙\n */\nexport interface ArchetypeEnforcementRules {\n  /** Actions this archetype uses most frequently */\n  readonly preferredActions: readonly AIActionType[];\n  \n  /** Actions this archetype never uses (philosophy conflicts) */\n  readonly prohibitedActions: readonly AIActionType[];\n  \n  /** Signature technique ID for this archetype */\n  readonly signatureMove: string;\n  \n  /** Condition function to trigger signature move */\n  readonly signatureCondition: (context: CombatContext) => boolean;\n  \n  /** Target frequency distribution for each action type (0.0-1.0) */\n  readonly actionFrequencies: Readonly<Record<AIActionType, number>>;\n}\n\n/**\n * Archetype enforcement rules for all 5 player archetypes\n * \n * Defines distinct combat philosophies with measurable behavior patterns\n * that make each archetype immediately identifiable through AI actions.\n * \n * @korean 5대 원형 강화 규칙\n */\nexport const ARCHETYPE_ENFORCEMENT: Record<PlayerArchetype, ArchetypeEnforcementRules> = {\n  [PlayerArchetype.MUSA]: {\n    preferredActions: [AIActionType.ATTACK, AIActionType.APPROACH, AIActionType.TECHNIQUE],\n    prohibitedActions: [AIActionType.FEINT], // Honor code: No deception\n    signatureMove: \"musa_mountain_breaker\",\n    signatureCondition: (context) => {\n      /**\n       * Musa (무사) signature move condition: Mountain Breaker when opponent <40% health\n       * \n       * NOTE: Uses opponentMaxHealth if available, otherwise assumes symmetric max-health\n       * pools (context.playerMaxHealth === opponentMaxHealth). If asymmetric max health\n       * exists, CombatContext provides opponentMaxHealth for accurate calculation.\n       */\n      const maxHealth = context.opponentMaxHealth ?? context.playerMaxHealth;\n      if (maxHealth <= 0) {\n        // Defensive guard: avoid divide-by-zero / invalid percentages\n        return false;\n      }\n      const opponentHealthPercent = context.opponentHealth / maxHealth;\n      return opponentHealthPercent < 0.40; // Finishing move when opponent <40% health\n    },\n    actionFrequencies: {\n      /**\n       * Musa (무사) Action Frequencies - Honor Code Warrior\n       * \n       * These frequencies represent behavioral targets (not strict probability distributions).\n       * Multiple actions can have high frequencies as they represent overlapping aggressive behavior.\n       * \n       * **Honor Code Rules**:\n       * - FEINT: 0% (prohibited - no deception)\n       * - RETREAT: 2% (minimal - only at critical health <10%, handled by evaluateSurvival)\n       * - DEFEND: 10% (minimal - offense-focused philosophy)\n       * \n       * The 2% retreat frequency applies only when health drops below the honor threshold (~5-10%),\n       * enforced by evaluateSurvival logic. Above this threshold, Musa never retreats.\n       */\n      [AIActionType.ATTACK]: 0.70, // 70% aggressive attacks\n      [AIActionType.DEFEND]: 0.10, // 10% defense (honor code: minimal defense)\n      [AIActionType.RETREAT]: 0.02, // 2% retreat (only at critical health <10%)\n      [AIActionType.APPROACH]: 0.15, // 15% approach\n      [AIActionType.FEINT]: 0.00, // 0% feints (prohibited by honor code)\n      [AIActionType.TECHNIQUE]: 0.70, // 70% techniques (overlaps with attack)\n      [AIActionType.COUNTER]: 0.10, // 10% counters\n      [AIActionType.STANCE_CHANGE]: 0.10, // 10% stance changes\n      [AIActionType.CIRCLE]: 0.05, // 5% circling\n      [AIActionType.WAIT]: 0.03, // 3% wait\n      [AIActionType.COMBO]: 0.05, // 5% combos\n    },\n  },\n\n  [PlayerArchetype.AMSALJA]: {\n    preferredActions: [AIActionType.TECHNIQUE, AIActionType.CIRCLE, AIActionType.COUNTER],\n    prohibitedActions: [], // No prohibitions (pragmatic assassin)\n    signatureMove: \"amsalja_silent_death\",\n    signatureCondition: (context) => {\n      // Execute Silent Death when opponent is VULNERABLE or worse\n      return (\n        context.opponentBalance === \"VULNERABLE\" ||\n        context.opponentBalance === \"HELPLESS\"\n      );\n    },\n    actionFrequencies: {\n      [AIActionType.TECHNIQUE]: 0.60, // 60% techniques (vital point priority)\n      [AIActionType.CIRCLE]: 0.20, // 20% circling (stealth positioning to flanks/rear)\n      [AIActionType.ATTACK]: 0.15, // 15% basic attacks\n      [AIActionType.RETREAT]: 0.05, // 5% tactical retreats (at 60% health threshold)\n      [AIActionType.DEFEND]: 0.10, // 10% defense\n      [AIActionType.APPROACH]: 0.10, // 10% approach\n      [AIActionType.FEINT]: 0.10, // 10% feints\n      [AIActionType.COUNTER]: 0.20, // 20% counters\n      [AIActionType.STANCE_CHANGE]: 0.15, // 15% stance changes\n      [AIActionType.WAIT]: 0.05, // 5% wait\n      [AIActionType.COMBO]: 0.10, // 10% combos\n    },\n  },\n\n  [PlayerArchetype.HACKER]: {\n    preferredActions: [AIActionType.WAIT, AIActionType.TECHNIQUE, AIActionType.CIRCLE],\n    prohibitedActions: [], // Analytical, uses all tactics\n    signatureMove: \"hacker_system_crash\",\n    signatureCondition: (context) => {\n      // Execute System Crash after 20 seconds of observation (data collection phase)\n      return context.timeInMatch > 20000;\n    },\n    actionFrequencies: {\n      [AIActionType.WAIT]: 0.25, // 25% observation (data collection)\n      [AIActionType.TECHNIQUE]: 0.40, // 40% tech-assisted strikes\n      [AIActionType.CIRCLE]: 0.15, // 15% repositioning (maintain mid-range)\n      [AIActionType.ATTACK]: 0.15, // 15% basic attacks\n      [AIActionType.DEFEND]: 0.05, // 5% defense\n      [AIActionType.APPROACH]: 0.05, // 5% approach (prefers mid-range)\n      [AIActionType.RETREAT]: 0.10, // 10% retreat (maintain optimal distance)\n      [AIActionType.FEINT]: 0.05, // 5% feints\n      [AIActionType.COUNTER]: 0.15, // 15% counters\n      [AIActionType.STANCE_CHANGE]: 0.10, // 10% stance changes\n      [AIActionType.COMBO]: 0.05, // 5% combos\n    },\n  },\n\n  [PlayerArchetype.JEONGBO_YOWON]: {\n    preferredActions: [AIActionType.FEINT, AIActionType.COUNTER, AIActionType.TECHNIQUE],\n    prohibitedActions: [], // Psychological warfare, uses all tactics\n    signatureMove: \"jeongbo_precision_takedown\",\n    signatureCondition: (context) => {\n      // Execute Precision Takedown when opponent is HELPLESS (implemented in Issue #1186)\n      return context.opponentBalance === \"HELPLESS\";\n    },\n    actionFrequencies: {\n      [AIActionType.FEINT]: 0.30, // 30% psychological pressure (feints)\n      [AIActionType.TECHNIQUE]: 0.35, // 35% precision strikes\n      [AIActionType.COUNTER]: 0.20, // 20% counters\n      [AIActionType.WAIT]: 0.10, // 10% observation (strategic timing)\n      [AIActionType.ATTACK]: 0.05, // 5% basic attacks\n      [AIActionType.DEFEND]: 0.10, // 10% defense\n      [AIActionType.APPROACH]: 0.10, // 10% approach\n      [AIActionType.RETREAT]: 0.05, // 5% tactical retreats\n      [AIActionType.CIRCLE]: 0.15, // 15% circling (intimidation)\n      [AIActionType.STANCE_CHANGE]: 0.10, // 10% stance changes\n      [AIActionType.COMBO]: 0.05, // 5% combos\n    },\n  },\n\n  [PlayerArchetype.JOJIK_POKRYEOKBAE]: {\n    preferredActions: [AIActionType.ATTACK, AIActionType.TECHNIQUE, AIActionType.STANCE_CHANGE],\n    prohibitedActions: [], // No rules, survival at any cost\n    signatureMove: \"jojik_improvised_weapon\",\n    signatureCondition: (context) => {\n      /**\n       * Jojik (조직폭력배) signature move: Improvised Weapon when desperate (<30% health)\n       * \n       * This condition uses playerHealth (the AI's health) to trigger desperate tactics.\n       */\n      const maxHealth = context.playerMaxHealth;\n      if (maxHealth <= 0) {\n        // Defensive guard: avoid divide-by-zero\n        return false;\n      }\n      const playerHealthPercent = context.playerHealth / maxHealth;\n      return playerHealthPercent < 0.30; // Desperate improvised weapon when health <30%\n    },\n    actionFrequencies: {\n      /**\n       * Jojik (조직폭력배) Action Frequencies - Chaotic Survivor\n       * \n       * These frequencies represent behavioral targets for Jojik's unpredictable fighting style.\n       * \n       * **Key Behavioral Characteristics**:\n       * - STANCE_CHANGE: 80% (extremely high for unpredictability)\n       *   This means that in approximately 80% of decision cycles where a stance change\n       *   is a valid option, the AI will evaluate and strongly favor a stance change,\n       *   creating the erratic, chaotic movement pattern that defines Jojik's combat style.\n       * \n       * - RETREAT: 5% base, but survival instinct triggers tactical retreat at 70% health\n       *   (handled by evaluateSurvival logic with personality.tacticalRetreatThreshold)\n       * \n       * The high stance change frequency is the primary mechanism for Jojik's unpredictable behavior.\n       */\n      [AIActionType.ATTACK]: 0.50, // 50% chaotic attacks\n      [AIActionType.TECHNIQUE]: 0.25, // 25% dirty techniques\n      [AIActionType.STANCE_CHANGE]: 0.80, // 80% unpredictable stance changes (defines chaotic behavior)\n      [AIActionType.RETREAT]: 0.05, // 5% pragmatic retreats (survival instinct at 70% health via threshold)\n      [AIActionType.FEINT]: 0.05, // 5% deceptive moves\n      [AIActionType.DEFEND]: 0.10, // 10% defense\n      [AIActionType.APPROACH]: 0.15, // 15% approach\n      [AIActionType.COUNTER]: 0.10, // 10% counters\n      [AIActionType.CIRCLE]: 0.10, // 10% circling\n      [AIActionType.WAIT]: 0.03, // 3% wait\n      [AIActionType.COMBO]: 0.10, // 10% combos\n    },\n  },\n};\n\n/**\n * Enforce archetype-specific behavior on AI decision\n * \n * Applies philosophy-based restrictions and redirects to enforce distinct\n * combat patterns for each archetype. This ensures players can identify\n * which archetype they're fighting based on behavior alone.\n * \n * **Enforcement Logic**:\n * 1. Check for prohibited actions → Replace with preferred action\n * 2. Check for signature move condition → Override with signature move\n * 3. Return decision (possibly modified)\n * \n * @korean 원형 행동 강화\n * \n * @param decision - Original AI decision from DecisionTree\n * @param archetype - Player archetype to enforce\n * @param context - Current combat context\n * @returns Modified decision enforcing archetype philosophy\n */\nexport function enforceArchetypeBehavior(\n  decision: AIDecision,\n  archetype: PlayerArchetype,\n  context: CombatContext\n): AIDecision {\n  const rules = ARCHETYPE_ENFORCEMENT[archetype];\n\n  // Check for prohibited actions\n  if (rules.prohibitedActions.includes(decision.action)) {\n    // Replace with preferred action (random selection from preferred set)\n    // Defensive guard: Ensure preferredActions is not empty\n    if (rules.preferredActions.length === 0) {\n      console.warn(\n        `[ArchetypeEnforcer] ${archetype} has empty preferredActions array. Using original decision with warning.`\n      );\n      return {\n        ...decision,\n        reason: `Archetype enforcement: ${archetype} prohibited action ${decision.action}, but no alternatives available`,\n      };\n    }\n\n    const alternativeAction = rules.preferredActions[\n      Math.floor(Math.random() * rules.preferredActions.length)\n    ];\n\n    return {\n      ...decision,\n      action: alternativeAction,\n      reason: `Archetype enforcement: ${archetype} does not use ${decision.action} (원형 강화: ${decision.action} 사용 불가)`,\n    };\n  }\n\n  // Check for signature move condition\n  if (rules.signatureCondition(context)) {\n    // Override with signature move\n    return {\n      action: AIActionType.TECHNIQUE,\n      targetVitalPoint: undefined, // Let technique selection handle vital point targeting\n      priority: 10, // Maximum priority\n      reason: `Signature move: ${rules.signatureMove} for ${archetype} (서명 기술: ${rules.signatureMove})`,\n    };\n  }\n\n  // No enforcement needed - return original decision\n  return decision;\n}\n\n/**\n * Get signature move ID for archetype\n * \n * Returns the technique ID of this archetype's signature move.\n * Used for technique selection in useAICombat.ts.\n * \n * @korean 서명 기술 ID 가져오기\n * \n * @param archetype - Player archetype\n * @returns Signature technique ID\n */\nexport function getSignatureMove(archetype: PlayerArchetype): string {\n  return ARCHETYPE_ENFORCEMENT[archetype].signatureMove;\n}\n\n/**\n * Check if signature move condition is met\n * \n * Evaluates whether the archetype should execute its signature move\n * based on current combat context.\n * \n * @korean 서명 기술 조건 확인\n * \n * @param archetype - Player archetype\n * @param context - Current combat context\n * @returns True if signature move should be executed\n */\nexport function shouldExecuteSignatureMove(\n  archetype: PlayerArchetype,\n  context: CombatContext\n): boolean {\n  const rules = ARCHETYPE_ENFORCEMENT[archetype];\n  return rules.signatureCondition(context);\n}\n\n/**\n * Get action frequency target for archetype\n * \n * Returns the target frequency (0.0-1.0) for a specific action type\n * based on archetype combat philosophy.\n * \n * @korean 행동 빈도 목표 가져오기\n * \n * @param archetype - Player archetype\n * @param actionType - AI action type\n * @returns Target frequency for this action (0.0-1.0)\n */\nexport function getActionFrequency(\n  archetype: PlayerArchetype,\n  actionType: AIActionType\n): number {\n  return ARCHETYPE_ENFORCEMENT[archetype].actionFrequencies[actionType] ?? 0.0;\n}\n\n/**\n * Check if action is prohibited for archetype\n * \n * Returns true if the archetype's philosophy prohibits using this action.\n * \n * @korean 금지된 행동 확인\n * \n * @param archetype - Player archetype\n * @param actionType - AI action type to check\n * @returns True if action is prohibited\n */\nexport function isActionProhibited(\n  archetype: PlayerArchetype,\n  actionType: AIActionType\n): boolean {\n  return ARCHETYPE_ENFORCEMENT[archetype].prohibitedActions.includes(actionType);\n}\n"],"mappings":"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"}

package/lib/systems/ai/ComboSystem.d.ts

@@ -0,0 +1,136 @@
+/**
+ * AI Combo System for Korean Martial Arts
+ * Manages multi-hit combo sequences based on trigram stances and archetype signature combos
+ */
+import { PlayerState } from "../player";
+import { KoreanTechnique } from "../vitalpoint";
+import { PlayerArchetype, TrigramStance } from "../../types";
+import { AIPersonality } from "./AIPersonality";
+/**
+ * Combo sequence for a specific trigram stance
+ */
+export interface ComboSequence {
+    readonly stanceId: TrigramStance;
+    readonly techniques: readonly KoreanTechnique[];
+    readonly minDistance: number;
+    readonly maxDistance: number;
+    readonly requiredKi: number;
+    readonly requiredStamina: number;
+    readonly name: {
+        readonly korean: string;
+        readonly english: string;
+    };
+}
+/**
+ * Archetype signature combo sequence (2-3 technique chains)
+ *
+ * These are special technique sequences that represent each archetype's
+ * fighting philosophy and preferred combat patterns.
+ *
+ * @korean 원형 대표 연계 기술
+ */
+export interface ArchetypeComboSequence {
+    readonly archetype: PlayerArchetype;
+    readonly techniqueIds: readonly string[];
+    readonly name: {
+        readonly korean: string;
+        readonly english: string;
+    };
+    readonly description: {
+        readonly korean: string;
+        readonly english: string;
+    };
+}
+/**
+ * Archetype Signature Combos
+ *
+ * Each archetype has 2 signature combo sequences that reflect their combat philosophy.
+ * These combos are prioritized by AI for authentic fighting style representation.
+ *
+ * Combo patterns:
+ * - Musa: Power amplification and defense-to-offense transitions
+ * - Amsalja: Setup-to-execution nerve strike sequences
+ * - Hacker: Analysis-to-burst and stun-to-shutdown patterns
+ * - Jeongbo: Weaken-to-exploit and counter-to-finish sequences
+ * - Jojik: Chaos-to-brutality and aggression-to-desperation patterns
+ *
+ * @korean 원형 대표 연계 기술 정의
+ */
+export declare const ARCHETYPE_SIGNATURE_COMBOS: Record<PlayerArchetype, readonly ArchetypeComboSequence[]>;
+/**
+ * Get next technique in archetype signature combo
+ *
+ * Checks if current technique is part of a signature combo sequence,
+ * and returns the next technique in that sequence if found.
+ *
+ * @korean 원형 대표 연계 기술의 다음 기술 가져오기
+ *
+ * @param currentTechniqueId - Current technique ID just executed
+ * @param archetype - Player archetype
+ * @returns Next technique ID in combo sequence, or undefined if no combo
+ */
+export declare function getNextComboTechnique(currentTechniqueId: string, archetype: PlayerArchetype): string | undefined;
+/**
+ * AI Combo System manages combo execution and decision-making
+ */
+export declare class AIComboSystem {
+    private comboSequences;
+    private currentCombo;
+    private comboProgress;
+    private lastComboTime;
+    private readonly comboTimeout;
+    constructor();
+    /**
+     * Initialize combo sequences for each trigram stance
+     */
+    private initializeComboSequences;
+    /**
+     * Get technique sequence for a stance
+     */
+    private getTechniqueSequence;
+    /**
+     * Calculate distance between two players
+     */
+    private getDistance;
+    /**
+     * Check if AI should continue current combo
+     *
+     * Enhanced with:
+     * - Opponent balance state checking (SHAKEN/VULNERABLE)
+     * - Combo length limit (max 3 techniques)
+     * - Stamina threshold (>20 for combo continuation)
+     *
+     * @korean 연계 기술 계속 여부 판단
+     */
+    shouldContinueCombo(player: PlayerState, opponent: PlayerState, personality: AIPersonality): boolean;
+    /**
+     * Start a new combo sequence
+     */
+    startCombo(player: PlayerState, opponent: PlayerState, personality: AIPersonality): boolean;
+    /**
+     * Get next technique in combo
+     */
+    getNextComboTechnique(): KoreanTechnique | null;
+    /**
+     * Reset current combo
+     */
+    resetCombo(): void;
+    /**
+     * Check if combo is active (fix for issue #2529727999)
+     */
+    isComboActive(): boolean;
+    /**
+     * Get combo progress information
+     */
+    getComboInfo(): {
+        active: boolean;
+        progress: number;
+        total: number;
+        percentage: number;
+    };
+    /**
+     * Get available combos for stance
+     */
+    getAvailableCombos(stance: TrigramStance): readonly ComboSequence[];
+}
+//# sourceMappingURL=ComboSystem.d.ts.map

package/lib/systems/ai/ComboSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComboSystem.d.ts","sourceRoot":"","sources":["../../../src/systems/ai/ComboSystem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAC7C,eAAe,EACf,SAAS,sBAAsB,EAAE,CAqJlC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,kBAAkB,EAAE,MAAM,EAC1B,SAAS,EAAE,eAAe,GACzB,MAAM,GAAG,SAAS,CAkBpB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;;IAMrC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAsIhC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiB5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;;;;;OASG;IACH,mBAAmB,CACjB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,aAAa,GACzB,OAAO;IAyDV;;OAEG;IACH,UAAU,CACR,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,aAAa,GACzB,OAAO;IAkCV;;OAEG;IACH,qBAAqB,IAAI,eAAe,GAAG,IAAI;IAc/C;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACH,aAAa,IAAI,OAAO;IASxB;;OAEG;IACH,YAAY,IAAI;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB;IAYD;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,aAAa,EAAE;CAGpE"}