関数の引数から安定かつ一意なキャッシュキーを生成できること。引数の型・構造に応じた正規化を行い、辞書のキー順序やコレクション型の違いを正しく区別できること。

コンポーネント構成

graph TD
  A[core.Spot] -->|キャッシュキー生成要求| B[KeyGenPolicy]
  B -->|バインド| C[bound_keygen]
  C -->|引数別戦略| D[Strategy]
  C -->|正規化| E[canonicalize]
  C -->|ハッシュ計算| F[KeyGen.hash_items]
  E --> F

コンポーネント責務

データフロー

sequenceDiagram
  participant Spot as core.Spot
  participant KP as KeyGenPolicy
  participant Sig as inspect.signature
  participant Can as canonicalize
  participant KG as KeyGen

  Spot->>KP: bind(func)
  KP->>Sig: signature(func)
  Sig-->>KP: bound_keygen 生成
  KP-->>Spot: bound_keygen
  Spot->>Spot: bound_keygen(*args, **kwargs)
  loop 各引数
    alt Strategy.IGNORE
      Spot->>Spot: スキップ
    else Strategy.FILE_CONTENT
      Spot->>KG: from_file_content(path)
    else Strategy.PATH_STAT
      Spot->>KG: from_path_stat(path)
    else Strategy.DEFAULT
      Spot->>Can: canonicalize(val)
      Can-->>Spot: 正規化済みデータ
    end
  end
  Spot->>KG: hash_items(items_to_hash)
  KG-->>Spot: SHA-256 ハッシュ文字列 (キャッシュキー)

技術選定

非機能要件方針

• 安定性: プロセスの再起動やPythonのバージョン（辞書の順序等）に依存せず、同一入力に対して常に同一のハッシュを生成すること。
• 性能: 複雑なオブジェクト構造でも高速に正規化とハッシュ計算を行えること。ファイル内容のハッシュ化はチャンク読み込みでメモリ効率を確保する。
• 拡張性: ユーザーが独自の KeyGenPolicy を定義可能にし、柔軟なキャッシュ戦略をサポートする。

インターフェース

class KeyGen:
    @staticmethod
    def _default(args: tuple, kwargs: dict) -> str: ...

    @staticmethod
    def hash_items(items: list) -> str: ...

振る舞い

基本フロー (_default)

1. 正規化: args と kwargs を canonicalize() により再帰的に正規化する
2. パック: 正規化された構造 [args, kwargs] を MessagePack でバイナリにシリアライズする
3. ハッシュ: バイナリデータに対して SHA-256 ハッシュを計算し、16進数文字列を返す

リストハッシュ (hash_items)

• 任意個の正規化済みアイテムを含むリストを受け取り、一括でパックしてハッシュ化する。KeyGenPolicy で使用される。

パラメータ詳細

エラーハンドリング

• 再帰制限超過: RecursionError 発生時は、安全のため str((args, kwargs)) のハッシュをフォールバックとして使用する
• パック失敗: MessagePack シリアライズに失敗した場合は、警告をログ出力した上で str() ベースのハッシュを返す

エッジケース

• 空の引数: 引数なしの場合も [(), {}] の構造として一定のハッシュ値を生成する
• 非決定的な repr: フォールバック時の str() はオブジェクトによっては実行ごとに変わる可能性があるため、明示的な正規化が推奨される

インターフェース

@singledispatch
def canonicalize(obj: Any) -> Any: ...

振る舞い

singledispatch を使用し、型に応じた最適な正規化形式へ再帰的に変換する。

主要な型別の処理

• 基本型 (int, float, str, bytes): そのまま返す
• bool: ("__bool__", value) のタプルに変換（1 と True の衝突を防止）
• dict: キーでソートし、[[k1, v1], [k2, v2], ...] のリストに変換
• list / tuple / set / frozenset / deque: それぞれ専用の型タグ（例: "__list__") を付与し、要素を再帰的に正規化。集合型はソートを行う
• Enum: ("__enum__", module, qualname, value) に変換
• カスタムオブジェクト: __dict__ または __slots__ から属性を取得し、型名と共に正規化

パラメータ詳細

エラーハンドリング

• 未対応型: 警告をログ出力し、str(obj) にフォールバックする
• 循環参照: RecursionError をキャッチし、その階層で str() による正規化に切り替える

エッジケース

• 異なる型の比較: _safe_sort_key により、Python 3 で比較不可能な型同士（例: int と str）が辞書のキーに含まれていても安定したソート順を保証する

インターフェース

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() で一つのハッシュにまとめる

パラメータ詳細

エラーハンドリング

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

エッジケース

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

目的

キャッシュキーはキャッシュの同一性判定の基盤であり、ハッシュが不安定だとキャッシュミスの頻発（性能劣化）や誤ヒット（データ不整合）を引き起こす。Python バージョンやプラットフォームに依存しないキー生成の安定性を保証する。

検証観点

• 決定性: 同一の func_identifier:input_id[:version] 入力に対して、複数回の呼び出しで常に同じ SHA-256 ハッシュが生成されること
• 一意性: 異なる引数から異なるキーが生成されること（衝突しないこと）
• 構造: キーが module.qualname 形式の func_identifier を含む正しい構造であること
• version 反映: version 文字列がキーに含まれ、version 変更でキーが変わること

目的

canonicalize() は引数の型ごとに正規化ルールを適用し、論理的に同値な入力が同じキャッシュキーを生成することを保証する。正規化の不備は「同じ入力なのにキャッシュミス」または「異なる入力なのに誤ヒット」という致命的なバグに直結する。

検証観点

• dict の順序非依存: {"a": 1, "b": 2} と {"b": 2, "a": 1} が同一キーを生成すること
• 型タグによる区別: [1, 2] (list) と (1, 2) (tuple) が異なるキーを生成すること（型タグ付き正規化）
• set/frozenset: 要素の挿入順序に依存しないこと
• deque/defaultdict/OrderedDict: コレクション型ごとに正しく正規化されること
• Enum: 値ではなく 型名.メンバー名 で正規化されること
• numpy 配列: shape + dtype + tobytes による正規化で、同値配列が同一キーを生成すること
• Pydantic モデル: モデルの dict 表現で正規化されること
• bool vs int の区別: True と 1 が異なるキーを生成すること（Python では True == 1 だが区別が必要）
• 再帰的処理: ネストされたデータ構造（dict の中の list の中の set 等）が正しく正規化されること

目的

KeyGenPolicy は引数ごとのキー生成戦略をカスタマイズする機構であり、ログレベルやデバッグフラグのような非決定的引数をキーから除外したり、ファイルパスの代わりにファイル内容でキーを生成するユースケースを支える。戦略の誤適用はキャッシュの正確性を根本から損なう。

検証観点

• KeyGen.ignore(): 指定された引数がキャッシュキーの計算から除外され、その引数の値を変えてもキャッシュヒットすること
• KeyGen.map() + FILE_CONTENT: ファイルパス引数に対し、パス文字列ではなくファイル内容のハッシュがキーに使われること。同一内容の別パスファイルが同一キーを生成すること
• KeyGen.path_stat(): ファイルの mtime/size に基づくキー生成が機能すること
• bind() 連携: KeyGenPolicy.bind(func) が関数シグネチャ（位置引数・キーワード引数・デフォルト値）を正しく解釈すること
• @mark 統合: @spot.mark(keygen=KeyGen.ignore("verbose")) のようにデコレータ経由で戦略が正しく適用されること

実装概要

KeyGen クラスの静的メソッド群がキャッシュキー生成を担う。 _default(args, kwargs) が主要なエントリポイントで、引数を canonicalize() で正規化 → msgpack でシリアライズ → SHA-256 でハッシュする。 最終キーは func_identifier:input_id[:version] 形式の文字列を SHA-256 した値。

設計判断

SHA-256 の採用

MD5 より衝突耐性が高く、Python 標準ライブラリの hashlib で利用可能。 キャッシュキーとして64文字の hex 文字列は十分にコンパクトで、 DB のインデックスとしても効率的。

msgpack 経由のシリアライズ

正規化結果を直接 str() でハッシュする方式と比較し、 msgpack はバイナリ表現が安定しており、Python バージョン間での repr() の差異に影響されない。

ファイルベースの戦略

from_file_content() はファイルを 65KB チャンクで読み取り、 拡張子をハッシュに含める。大きなファイルでもメモリ効率が良い。 from_path_stat() は mtime + size のみでハッシュし、 ファイル内容の読み取りを避ける高速版。ファイル不在時は "MISSING_{filepath}" を返し、不在自体をキーに反映する。

実装メモ

• hash_items() は汎用リストハッシュ。内部でも _default でも使われる
• kwargs は dict をソートしてからハッシュするため、引数の順序に非依存

実装概要

canonicalize() は functools.singledispatch で実装された再帰的正規化関数。 型ごとにディスパッチハンドラを登録し、ネストされたデータ構造を再帰的に正規化する。 各ハンドラは型タグ付きのタプルを返し、異なるコレクション型が同じ内容でも 区別されるようにする。

設計判断

singledispatch の採用

if/elif チェーンと比較して、新しい型のサポート追加が局所的で、 既存コードへの影響がない。numpy や Pydantic のようなオプショナル依存の 型ハンドラも、条件付きで登録できる。

型タグによるコレクション区別

[1, 2]（list）と (1, 2)（tuple）を区別するため、 正規化結果に ("__list__", ...), ("__tuple__", ...) のように 型タグを含める。これにより、構造的に同一でも型が異なるデータが 異なるキャッシュキーを生成する。

bool vs int の区別

Python では True == 1 かつ isinstance(True, int) だが、 キャッシュキーとしては区別が必要。singledispatch は MRO 順でマッチするため、 bool を int より先にチェックするインライン処理を base handler に配置した。

実装メモ

• カスタムオブジェクトの正規化は __dict__ と __slots__ の両方を MRO 走査で収集する。 __dict__ スロット自体はスキップする
• OrderedDict は順序が意味を持つため、キーのソートを行わない（dict とは異なる）
• defaultdict は default_factory を無視し、内容のみで正規化する
• Enum は 型名.メンバー名 + value で正規化し、モジュール・qualname も含める
• 循環参照を検出した場合は str() にフォールバックし、警告を出力する（非決定的）
• 未知の型も str() にフォールバックするが、安定性は保証されない

実装概要

Strategy enum（DEFAULT, IGNORE, FILE_CONTENT, PATH_STAT の4種）と KeyGenPolicy クラスで構成。KeyGenPolicy は引数名→戦略のマッピングを保持し、 bind(func) で inspect.signature() を使って関数シグネチャにバインドされた キー生成関数を返す。ファクトリメソッド KeyGen.ignore(), KeyGen.map(), KeyGen.file_content(), KeyGen.path_stat() で宣言的にポリシーを構築できる。

設計判断

bind() によるシグネチャバインディング

デコレーション時に inspect.signature(func) を呼び、 位置引数・キーワード引数・デフォルト値を解決する。 これにより、呼び出し時にはシグネチャ解析のオーバーヘッドがなくなる。

Strategy enum による宣言的指定

引数ごとの戦略を enum で宣言する方式を採用。 関数を渡す方式（keygen=lambda ...）と比較して、 シリアライズ可能で、デバッグ時の可読性が高い。

実装メモ

• bind() 内で RecursionError を catch し、警告を出力してフォールバックする
• FILE_CONTENT 戦略は KeyGen.from_file_content() に委譲し、65KB チャンク読み取りを行う
• PATH_STAT 戦略は KeyGen.from_path_stat() に委譲し、mtime + size でハッシュする
• IGNORE 戦略の引数はキー計算から完全に除外される（値に関係なくキャッシュヒット）

Stable Hashing for Function Arguments

Context and Problem Statement / コンテキスト

beautyspot のコア機能である「関数のメモ化（キャッシュ）」において、関数の引数 (args, kwargs) から一意なキャッシュキーを生成する必要があります。

初期実装 (v0.1.0) では、json.dumps が失敗した場合のフォールバックとして str((args, kwargs)) のハッシュ値を使用していました。

しかし、Pythonのデフォルトの __str__ / __repr__ 実装は、オブジェクトのメモリアドレス（例: <MyObject at 0x10a...>）を含むことが多くあります。

これにより以下の問題が発生していました：

1. 再起動ごとのキャッシュ無効化: プロセスを再起動するとメモリアドレスが変わり、同じ入力値でもハッシュが変わってしまう。
2. 分散環境での不整合: 異なるマシン（あるいは異なるプロセス）で実行した場合、キャッシュキーが一致しない。

外部ライブラリ（joblib 等）を使えば解決しますが、beautyspot は軽量な「黒子」ライブラリを目指しており、依存関係を増やしたくありません。

Decision Drivers / 要求

• Stability across restarts: プロセス再起動後もキャッシュが有効に機能すること。
• Environment Independence: 異なるマシンや環境間でも一貫したハッシュ値が得られること。
• Zero External Dependencies: 軽量さを維持するため、外部ライブラリ（joblib, numpy等）に依存しないこと。
• Broad Type Support: pydantic モデルや dataclass 等、一般的なPythonオブジェクトを透過的に扱えること。

Considered Options / 検討

• Option 1: 現状維持（str() によるフォールバック）。
• Option 2: 外部ライブラリ（joblib 等）の導入。
• Option 3: 標準ライブラリの json を拡張した、独自の安定化シリアライザの実装。

Decision Outcome / 決定

Chosen option: Option 3.

標準ライブラリの json モジュールを使用し、独自の default シリアライザ (_stable_serialize_default) を実装することで、依存関係なしで 堅牢なハッシュ生成を実現します。

具体的には以下の戦略を採用します：

1. Set/Frozensetのソート: JSONは順序を持たない集合を扱えないため、sorted(list(obj)) でリスト化し、順序を保証します。
2. カスタムオブジェクトの辞書化: __dict__ または __slots__ を参照し、オブジェクトの「中身の値」をシリアライズ対象とします。これにより、メモリアドレスへの依存を排除します。
3. Bytes型: 16進数文字列 (hex) に変換します。
4. 最終手段: それでもシリアライズできない型（循環参照など）については、例外的に str() を使用します（この場合のみ不安定になるリスクを許容します）。

Consequences / 決定

• Positive:
  • アプリ再起動後もキャッシュが有効に機能する（永続化の信頼性向上）。
  • pydantic モデルや dataclass も設定なしでキャッシュ可能になる。
  • 外部依存（numpy, joblib 等）を増やさずに済む。
• Negative:
  • 単なる str() 変換よりも、シリアライズ処理のオーバーヘッド（CPUコスト）がわずかに増加する。
  • 循環参照を持つオブジェクトを渡された場合の完全な解決策ではない（ただし、タスクの入力引数としては稀であると判断）。

Canonical Input Serialization with Msgpack and SHA-256

Context and Problem Statement / コンテキスト

beautyspot はこれまで、キャッシュキーの生成に json.dumps(sort_keys=True) と MD5 を使用していました。 しかし、以下の課題が顕在化していました：

1. バイナリデータの非効率性: Numpy配列や画像データなどをJSON化する際、テキスト変換（tolist() や str()）による巨大なオーバーヘッドとメモリ消費が発生する。
2. ハッシュの衝突リスク: str() に依存したフォールバックでは、巨大なNumpy配列が省略表示（...）された際にハッシュが衝突し、誤ったキャッシュヒットを引き起こす危険性がある。
3. アルゴリズムの老朽化: MD5 は現代のセキュリティ基準では非推奨とされており、コンプライアンス上の懸念がある。

Decision Drivers / 要求

• Accuracy: 入力データが少しでも異なれば、確実に異なるキーを生成したい（特にNumpy配列）。
• Performance: バイナリデータを効率的に扱いたい。
• Consistency: 入力（キー生成）も出力（データ保存）も msgpack エコシステムで統一したい。

Considered Options / 検討

• Option 1: json.dumps(sort_keys=True) と MD5 を継続利用する。
• Option 2: msgpack を用いた独自正規化ロジックと SHA-256 を採用する。

Decision Outcome / 決定

Chosen option: Option 2.

キャッシュキー生成ロジックを以下のように刷新します：

1. Canonicalization (正規化):
   • 独自の正規化関数 canonicalize(obj) を実装する。
   • Dict: キーでソートされた「タプルのリスト [[k, v], ...]」に変換し、順序を固定する。
   • Set: ソートされたリストに変換する。
   • Numpy: numpy をインポートせず、Duck Typing（shape, dtype, tobytes 属性の確認）により検知し、生のバイト列を含むタプルに変換する。これにより完全な一意性を保証する。
2. Serialization:
   • 正規化されたオブジェクトを msgpack でシリアライズする。
3. Hashing:
   • ハッシュアルゴリズムを SHA-256 に変更する。

Consequences / 決定

• Positive:
  • Numpy配列などのバイナリデータに対するハッシュ生成が劇的に高速化・省メモリ化される。
  • 省略表示によるハッシュ衝突バグが解消される。
  • pickle を使用しないため、安全性（RCEフリー）が維持される。
• Negative:
  • 破壊的変更: 既存のキャッシュ（v1.x）とはキーが一致しなくなるため、v2.0.0 でのリリースが必要。
  • 巨大で深くネストした辞書データの場合、Python側での正規化処理により若干のオーバーヘッド増が発生する可能性がある。

Refactoring Complex Modules with Single Dispatch

Context and Problem Statement / コンテキスト

quality_report により、src/beautyspot/cachekey.py の canonicalize 関数が非常に高い循環的複雑度（ランク D）を持っていることが判明しました。この関数は、ハッシュ化のためのオブジェクト正規化において、dict, list, set, numpy, type など多岐にわたる型をチェックするために長い if-elif-else チェーンを使用していました。

この構造は開放閉鎖の原則 (Open-Closed Principle) に違反しており、新しい型のサポートを追加するたびにコア関数を修正する必要があるため、退行（デグレード）のリスクを高めていました。

Decision Drivers / 要求

• Maintainability: 高い複雑度を解消し、各型の処理ロジックを独立させること。
• Extensibility: 既存のコードを変更することなく、新しい型への対応を容易にすること。
• Readability: 1つの関数が負うべき責任を明確にし、コードの可読性を向上させること。

Considered Options / 検討

• Option 1: 現状の巨大な if-elif チェーンを維持する。
• Option 2: Python 標準ライブラリの functools.singledispatch を使用してリファクタリングする。

Decision Outcome / 決定

Chosen option: Option 2.

canonicalize 関数を functools.singledispatch を用いて刷新します。

• Default Dispatch: プリミティブ型、フォールバックロジック (str)、およびダックタイピングによるチェック（Numpy 配列や __dict__ を持つオブジェクト等）を処理する。
• Registered Handlers: dict, list, tuple, set, frozenset, type 等の特定のロジックは、装飾された独立した関数に移動する。

Consequences / 決定

• Positive:
  • 複雑度の低減: メイン関数のロジックが、焦点を絞った小さなハンドラに分割される。
  • 拡張性: 既存コードを変更せずに、新しいハンドラを登録するだけで将来の型をサポートできる。
  • 可読性: 各ハンドラが単一の型に対する責任に集中できる。
• Negative:
  • ダックタイピングの制限: singledispatch は厳密な型に基づいているため、Numpy のようなダックタイピングによるチェックは依然としてデフォルトハンドラや基底層で行う必要がある。