active: true
derived: false
gherkin: |
  Feature: KeyGenPolicy strategy
    Scenario: Applying custom strategies to specific arguments
      Given a function with a bound KeyGenPolicy
      When the function is called with arguments
      Then it applies the configured strategies (e.g., IGNORE, FILE_CONTENT) to generate the cache key
groups:
- KEY
header: |
  KeyGenPolicy 戦略
level: 2.6
links:
- ARCH002: HVEL9BgCJqagLk2CA_ksXF9TleinSEfxiUcowkxwoJs=
normative: true
ref: ''
reviewed: ekqwcPXDF6SoFg78leXwJRbFBAk5osCGbgN3S_6TMZI=
text: |
  ## インターフェース

  ```python
  class Strategy(Enum):
      DEFAULT = auto()      # 再帰的正規化
      IGNORE = auto()       # キー計算から除外
      FILE_CONTENT = auto() # ファイルの内容をハッシュ
      PATH_STAT = auto()    # パス+サイズ+更新時刻をハッシュ

  class KeyGenPolicy:
      def bind(self, func: Callable) -> Callable[..., str]: ...
  ```

  ## 振る舞い

  1. **バインド**: `bind(func)` 時に `inspect.signature` を解析し、引数名とデフォルト値を把握する
  2. **適用**: 呼び出し時に引数を実値にバインドし、デフォルト値を補填する
  3. **戦略実行**: 引数名ごとに指定された `Strategy` を適用し、正規化された値のリストを作成する
  4. **集約**: 全ての値を `KeyGen.hash_items()` で一つのハッシュにまとめる

  ## パラメータ詳細

  | 戦略 | 内容 | 用途 |
  |---|---|---|
  | `IGNORE` | キャッシュキーに含めない | `verbose` や `logger` 等、結果に影響しない引数 |
  | `FILE_CONTENT` | ファイルを全読込してハッシュ化 | 入力ファイルの厳密な変更検知 |
  | `PATH_STAT` | `os.stat` 情報を使用 | 大容量ファイルの高速な変更検知 |

  ## エラーハンドリング

  - **ファイル不在**: `FILE_CONTENT` / `PATH_STAT` 指定時にファイルがない場合、`"MISSING_{path}"` という固定文字列をハッシュ対象とする
  - **アクセスエラー**: ファイル読み込み失敗時は `"ERROR_{path}"` を返す

  ## エッジケース

  - **シグネチャ不一致**: 引数が関数のシグネチャと合わない場合は `TypeError` を送出する（実行前バリデーション）
  - **デフォルト値の変更**: 関数のデフォルト値が変わると、同じ引数でもハッシュ値が変わる（意図的な挙動）

  ## 設計判断

  「DBの接続オブジェクト」や「テンポラリファイル」など、キャッシュキーに含めるべきではない引数を柔軟に除外できるようにするため。ユーザーに細かい制御手段を提供し、キャッシュの誤動作を防ぐ。
