• Beautyspot: 本キャッシュライブラリの名称。

• Spot: 本ライブラリにおけるキャッシュ・レート制限のコアエンジンの名称。

• キャッシュキー (Cache Key): 関数の入力引数等から一意に生成される識別子。

• キャッシュヒット: 保存された結果を再利用し、元の関数を実行しないこと。

• キャッシュミス: 結果が未保存または無効のため、元の関数を実行すること。

• メタデータDB (Metadata DB): キャッシュの有効期限、サイズ、関数名などの付帯情報を保存するデータストア。

• Blobストレージ (Blob Storage): キャッシュの実際のペイロード（戻り値のシリアライズ結果）を保存するストレージ。

• シリアライザ (Serializer): 関数の戻り値をストレージに保存可能なバイト列等に変換、および復元するコンポーネント。

• バックグラウンドIO (Background IO): メインスレッド（またはタスク）の実行をブロックせず、非同期にキャッシュ保存などを行う仕組み。

• レート制限 (Rate Limiting): 外部API呼び出し等の頻度を制御する仕組み。トークンバケット方式を採用。

• Thundering Herd: キャッシュミス時に、多数の並行リクエストが同時に同一関数を実行しようとして過負荷になる現象。

• フック (Hook): キャッシュのライフサイクル（ヒット、ミス、保存前後等）に介入できるコールバック機構。

• 依存注入 (Dependency Injection / DI): 各コンポーネント（DB、ストレージ等）を外部から差し替え可能にする設計パターン。

仕様書の機能グループ (Groups)

仕様書アイテムに付与される groups 属性の意味は以下の通りです。

背景・動機

ドキュメント内で使われる概念を定義し、チーム内のコミュニケーション齟齬を未然に防ぐため。

関数の実行結果をキャッシュし、同一入力に対して再実行せずにキャッシュから結果を返せること。同期関数・非同期関数の両方をサポートすること。

背景・動機

データパイプラインや機械学習の実験、LLMのAPI呼び出しにおいて、同一入力に対する高コストな再実行を回避し、システムの応答速度向上とAPI課金の節約を同時に実現するため。

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

背景・動機

Pythonの多様なオブジェクト（辞書、リスト、カスタムクラス等）を入力とする関数において、意味的に同一の入力を正確に識別し、キャッシュのヒット率を最大化するとともに、意図しないキャッシュミスや誤ヒットを防ぐため。

キャッシュのメタデータ（関数名、入力ID、バージョン、有効期限等）をデータベースに永続化できること。

抽象インターフェースにより、DBやストレージなどのバックエンド実装を差し替え可能であること。

背景・動機

メタデータ（関数名、引数ハッシュ等）をRDBMSなどで管理することで、キャッシュの検索・有効期限管理・統計情報の取得を高速かつ一元的に行うため。また、柔軟なDI構造により、開発環境（SQLite）から本番環境（Redis/PostgreSQL等）へスケールアップ可能にする。

大きなキャッシュデータを外部ストレージ（ローカルファイルシステムやS3等）に保存できること。

DB直接保存とBlob保存を自動判定できること。

背景・動機

LLMの生成テキストや機械学習モデルの推論結果など、数MB〜数GBに及ぶ結果データをデータベース（SQLite等）に直接保存すると、DBの肥大化とパフォーマンス劣化を招くため、メタデータと実データを分離して管理するアーキテクチャが必要不可欠なため。

関数の戻り値を安全にシリアライズ・デシリアライズできること。ユーザー定義型のカスタムエンコーダ・デコーダを登録可能であること。

背景・動機

Pythonのオブジェクト（辞書やカスタムクラス等）を、バイト列としてDBやストレージに安全かつ効率的に永続化・復元するため。また、任意のオブジェクト（例: Pandas DataFrameやPydanticモデル）にも対応できる拡張性を提供するため。

キャッシュの保存処理をバックグラウンドで非同期に実行し、関数の応答レイテンシに影響を与えないモードを提供すること。

背景・動機

キャッシュの保存処理（DBへのインサートやファイル書き込み）がメインスレッドをブロックすると、関数の応答速度（レイテンシ）が悪化し、ユーザー体験を損なうため。キャッシュ保存の非同期化により、キャッシュ適用によるパフォーマンスのペナルティを実質ゼロにする。

キャッシュの有効期限を関数名パターンに基づくルールで設定できること。個別の関数に対して保持期間を指定でき、期限切れのキャッシュを自動的に無効化できること。

背景・動機

キャッシュデータは時間経過とともに価値が低下したり、ストレージ容量を圧迫したりするため。手動による削除運用を不要にし、自動的かつ柔軟に古いデータを無効化・削除する仕組みを提供することで、メンテナンスコストを削減する。

関数の実行頻度をトークンバケット方式で制限し、外部APIの呼び出しレートを制御できること。同期・非同期の両方に対応すること。

背景・動機

外部API（特にLLMのAPIなど）は、利用制限（Rate Limit）が厳しく設定されていることが多く、短時間での過剰なリクエストによるエラー（HTTP 429等）を防ぐため。キャッシュだけでなくAPI呼び出し自体の安定性を高める。

関数の実行前、キャッシュヒット時、キャッシュミス時にカスタムコールバック（フック）を実行できること。スレッドセーフなフック実装を提供すること。

背景・動機

ユーザーが関数のビジネスロジックを汚すことなく、キャッシュヒット率の計測、LLMのトークン消費量のトラッキング、あるいはカスタムログの出力などの横断的関心事（Cross-cutting concerns）を柔軟に差し込めるようにするため。

期限切れキャッシュの削除、孤立Blobファイルのガベージコレクション、時間ベースの一括削除（prune）等のメンテナンス操作ができること。

背景・動機

運用が長期化するにつれて、無効になったキャッシュデータや孤立したファイルがストレージを逼迫するため。運用者がストレージを健全に保つための管理機能（定期クリーンアップ等）を提供し、システムダウンを防ぐ。

コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、GC等の管理操作ができること。

背景・動機

開発時や運用時に、現在のキャッシュの状況確認や不要なキャッシュの手動削除を、Pythonコードを書かずにコマンドラインから直感的に素早く実行できるようにするため。

全コンポーネント（DB、ストレージ、シリアライザ、リミッター等）が Protocol/ABC に基づく依存注入により差し替え可能であること。ファクトリ関数がデフォルトの組み立てを提供すること。

背景・動機

プロジェクトの規模や要件（ローカルでのプロトタイピングから、クラウド上での分散デプロイまで）の変化に合わせて、キャッシュバックエンドやストレージを柔軟に入れ替え可能にし、ライブラリの汎用性を極大化するため。

同一キャッシュキーに対する並行リクエストを直列化し、1つのリクエストのみが関数を実行し、他のリクエストはその結果を共有することで重複実行を防止できること。

背景・動機

同一の重い計算処理やAPI呼び出しに対して、複数スレッド/プロセスから同時にリクエストが殺到した際、キャッシュミスとなって無駄な再実行が多重に発生する（Thundering Herd問題）のを防ぎ、システムリソースを保護するため。

データベース操作が指定されたタイムアウト時間内に完了しない場合、呼び出し元を無期限にブロックせずにエラーを返し、システムの可用性を維持すること。特にSQLiteの書き込みスレッドがスタックした場合でも、フェイルファストによって制御を戻せること。

背景・動機

重い計算処理やLLM呼び出しのキャッシュ層がボトルネックとなり、システム全体の停止を招くことを防ぐため。キャッシュの保存や取得の失敗はログに留め、メインの処理は続行させる「グレースフル・デグラデーション」を保証する。

コンポーネント構成

graph TD
  A[bs.Spot Factory] -->|DI/Composition| B[core.Spot]
  B --> C[TaskDBBase]
  B --> D[SerializerProtocol]
  B --> E[BlobStorageBase]
  B --> F[StoragePolicyProtocol]
  B --> G[LimiterProtocol]
  B --> H[LifecyclePolicy]

コンポーネント責務

データフロー

sequenceDiagram
  participant User as ユーザーコード
  participant Spot as core.Spot
  participant DB as TaskDB
  participant Ser as Serializer
  participant Blob as BlobStorage

  User->>Spot: fn(args)
  Spot->>DB: find_by_key(cache_key)
  alt キャッシュヒット
    DB-->>Spot: cached_data
    Spot->>Ser: unpack(data)
  else キャッシュミス
    Spot->>Spot: fn(args) 実行
    Spot->>Ser: pack(result)
    Spot->>DB: insert(metadata)
    opt Blob保存
      Spot->>Blob: save(key, data)
    end
  end
  Spot-->>User: result

技術選定

非機能要件方針

• 透過性: ユーザー関数の入出力に影響を与えないこと。
• 拡張性: 全コンポーネントはProtocol/ABCで抽象化し、DIで差し替え可能とすること。

設計根拠

キャッシュ機能の複雑さ（DB、ストレージ、シリアライズ、ライフサイクル）をユーザーから隠蔽しつつ、内部コンポーネントを粗結合に保つため。Spotクラスを中心としたDI（依存性注入）アーキテクチャにより、柔軟な拡張とテスト容易性を実現した。

コンポーネント構成

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 を定義可能にし、柔軟なキャッシュ戦略をサポートする。

設計根拠

入力引数の正規化・ハッシュ化は複雑になりがちなため、PolicyとStrategyのパターンを用いて「どう正規化するか」と「どの引数を対象にするか」を分離。これにより、ユーザーが特定の引数をハッシュ計算から除外するなどのカスタマイズを容易にした。

コンポーネント構成

classDiagram
  class TaskDBCore {
    <<Protocol>>
    +init_schema() void
    +get(cache_key) TaskRecord
    +save(cache_key, ...) void
    +delete(cache_key) bool
  }
  class Maintenable {
    <<Protocol>>
    +delete_expired() int
    +prune(older_than) int
    +delete_all() int
  }
  class TaskDBMaintenable {
    <<Protocol>>
  }
  TaskDBCore <|-- TaskDBMaintenable
  Maintenable <|-- TaskDBMaintenable

  class SQLiteTaskDB {
    -db_path: Path
    -_write_queue: Queue
    +init_schema() void
    +get(cache_key) TaskRecord
    +save(cache_key, ...) void
  }
  TaskDBMaintenable <|-- SQLiteTaskDB

コンポーネント責務

データフロー

sequenceDiagram
  participant Spot as core.Spot
  participant DB as SQLiteTaskDB
  participant Q as WriteQueue
  participant Thread as WriterThread
  participant SQLite as SQLiteDB

  Spot->>DB: get(cache_key)
  DB->>SQLite: SELECT
  SQLite-->>DB: TaskRecord
  DB-->>Spot: TaskRecord

  Spot->>DB: save(metadata)
  DB->>Q: put(WriteTask)
  DB-->>Spot: void (Non-blocking)

  Thread->>Q: get()
  Thread->>SQLite: INSERT / UPDATE

技術選定

非機能要件方針

• 性能: 読み込みはメインスレッドで高速に処理（WALモード）、書き込みは専用スレッドによる非同期化。
• スレッド安全性: SQLiteへの書き込みは1つのスレッドに直列化し、データベースロックを回避する。
• 拡張性: すべての操作はProtocol (TaskDBCore, Maintenable) で定義され、利用側（core.Spotや_CacheManager）は実装に依存しない。

設計根拠

メタデータの永続化において、高速な検索とトランザクション管理が必要なため。RDBMSベース（SQLite）をデフォルトとしつつ、Protocolに基づく抽象化により将来的なRedisやPostgreSQLへの拡張性を担保する構成とした。

コンポーネント構成

graph TD
  A[core.Spot] -->|判定| B[StoragePolicyProtocol];
  A -->|保存/読込| C[BlobStorageBase];
  D[LocalStorage] --> C;
  E[S3Storage] --> C;
  A -->|メタデータ| F[TaskDBBase];

コンポーネント責務

データフロー

sequenceDiagram
  participant Spot as core.Spot
  participant Policy as StoragePolicy
  participant DB as TaskDB
  participant Blob as BlobStorage

  Spot->>Policy: should_save_as_blob(data)
  alt Policy: True (Blob保存)
    Spot->>Blob: save(key, data)
    Blob-->>Spot: location (path/URI)
    Spot->>DB: insert(metadata, storage_type=FILE, blob_key=location)
  else Policy: False (Inline保存)
    Spot->>DB: insert(metadata, storage_type=DIRECT_BLOB, result_data=data)
  end

技術選定

非機能要件方針

• 安全性: LocalStorage では is_relative_to によるパストラバーサル防止を徹底

• 信頼性: 保存時は fsync を実行し、OSレベルでのデータ到達を確認

• 効率性: S3 保存時は upload_fileobj を使用し、5GB超のマルチパートアップロードに自動対応

設計根拠

データサイズに応じた保存先の自動切り替え（小サイズはDB、大サイズはBlob）を透過的に実現するため。また、ローカルディスクとS3などのクラウドストレージを透過的に切り替えられるよう抽象化した。

コンポーネント構成

graph TD
  A[MsgpackSerializer] -->|Registry| B[TypeRegistryProtocol]
  A -->|LRU Cache| C[Thread-Local Storage]
  A -->|Core| D[msgpack-python]

コンポーネント責務

データフロー

sequenceDiagram
  participant User as ユーザーコード
  participant Ser as MsgpackSerializer
  participant Reg as TypeRegistry
  participant MP as msgpack

  User->>Ser: dumps(obj)
  Ser->>Ser: 型チェック & MRO解決
  opt カスタム型
    Ser->>Reg: エンコーダ取得
    Reg-->>Ser: encoder_fn
    Ser->>MP: ExtType(code, encoder_fn(obj))
  end
  MP-->>Ser: binary
  Ser-->>User: bytes

技術選定

非機能要件方針

• 性能: MRO（継承関係）解決結果をLRUキャッシュし、深層木探索のコストを最小化
• 柔軟性: ユーザー定義のエンコーダがプリミティブを返せば、再帰的にシリアライズ可能
• 堅牢性: デコード時の ExtCode 未登録エラーを検知し、互換性問題を明示的に報告

設計根拠

データのシリアライズにおいて、パフォーマンスと拡張性を両立させるため。MessagePackを基盤とし、型レジストリパターンを組み合わせることで、高速かつコンパクトなデータ変換とカスタム型のサポートを同時に実現した。

コンポーネント構成

graph TD
  A[core.Spot] -->|非同期タスク投入| B[_BackgroundLoop]
  B -->|Daemon Thread| C[asyncio.AbstractEventLoop]
  C -->|I/O| D[TaskDB / BlobStorage]
  A -->|ライフサイクル制御| E[atexit / ContextManager]

コンポーネント責務

データフロー

sequenceDiagram
  participant Main as メインスレッド
  participant BGLoop as _BackgroundLoop
  participant Store as ストレージ

  Main->>BGLoop: submit(save_coro)
  Note over Main: 関数は即座に結果を返す (save_sync=False)
  BGLoop->>Store: 書き込み実行 (I/O)
  alt 成功
      Store-->>BGLoop: OK
  else 失敗
      BGLoop->>Main: on_background_error(error)
  end

技術選定

非機能要件方針

• 透過性: 保存失敗時もユーザーコードの例外にはせず、コールバック経由で通知

• 一貫性: flush() により、クリティカルな処理の直後での保存完了を保証

• 安全性: シャットダウンシーケンス中に新規タスクを受け付けない排他制御を導入

設計根拠

同期処理に影響を与えずに非同期での保存を完了させるため。専用のバックグラウンドループ（デーモンスレッド）を用意し、メインスレッドのブロックを回避しつつ、アプリケーション終了時には確実にキューを消化する（atexit）仕組みを採用した。

コンポーネント構成

graph TD
  A[core.Spot] -->|マッチング要求| B[LifecyclePolicy]
  B -->|ルールリスト| C[Rule]
  C -->|パターン照合| D[fnmatch]
  B -->|パース| E[Retention]

コンポーネント責務

データフロー

sequenceDiagram
  participant Spot as core.Spot
  participant Policy as LifecyclePolicy
  participant DB as TaskDB

  Spot->>Policy: resolve_with_fallback("module.func")
  Policy->>Policy: ルール順次照合 (fnmatch)
  Policy-->>Spot: expires_at (timestamp)
  Spot->>DB: save(..., expires_at)
  Note over DB: get() 時に現在時刻と比較判定

技術選定

非機能要件方針

• 優先順位: 完全修飾名（モジュール名込み）が短縮名より優先される二段構えのマッチング
• 堅牢性: ポリシーにマッチしない場合は「無期限」とするフェイルセーフな設計
• 拡張性: Retention.FOREVER 等の定数により、グローバルポリシーの個別上書きに対応

設計根拠

関数ごとの有効期限管理を宣言的かつ柔軟に行うため。正規表現（fnmatch）によるパターンマッチングとパースロジックを分離し、一元的にポリシーを管理できる構成とした。

コンポーネント構成

graph TD
  A["@spot.consume"] -->|宣言的適用| B[LimiterProtocol]
  C[core.Spot] -->|DI| B
  D[TokenBucket] --> B
  D -->|アルゴリズム| E[GCRA]
  D -->|時刻同期| F[monotonic clock]

コンポーネント責務

データフロー

sequenceDiagram
  participant User as ユーザーコード
  participant Dec as @spot.consume
  participant Bucket as TokenBucket

  User->>Dec: call func()
  Dec->>Bucket: consume(cost)
  Bucket->>Bucket: 次回実行許可時刻の計算 (GCRA)
  alt 許可
      Bucket-->>Dec: OK
      Dec->>User: execute func()
  else 拒否 (Over rate)
      Bucket-->>Dec: raise ValueError/RateLimitError
  end

技術選定

非機能要件方針

• 正確性: time.monotonic() を使用し、システム時刻の変更（NTP同期等）の影響を受けない

• バースト制御: max_burst 設定により、アイドル後の過度なバーストを防止

• スレッド安全: threading.Lock により、マルチスレッド環境での二重消費を防止

設計根拠

レート制限を正確かつ低オーバーヘッドで実現するため。TokenBucketモデルとGCRA（Generic Cell Rate Algorithm）を採用し、タイムスタンプベースでの計算によって不要なスレッドロックを排除したアーキテクチャとした。

コンポーネント構成

graph TD
  A[core.Spot] -->|イベント通知| B[HookBase]
  C[ThreadSafeHookBase]　--> B
  B -->|コンテキスト| D[Context Objects]
  E[PreExecuteContext] --> D
  F[CacheHitContext] --> D
  G[CacheMissContext] --> D

コンポーネント責務

データフロー

sequenceDiagram
  participant Spot as core.Spot
  participant Hook as HookBase
  participant Fn as Target Function

  Spot->>Hook: pre_execute(ctx)
  alt キャッシュヒット
      Spot->>Hook: on_cache_hit(ctx)
  else キャッシュミス
      Spot->>Fn: execute()
      Fn-->>Spot: result
      Spot->>Hook: on_cache_miss(ctx)
  end

技術選定

非機能要件方針

• 透過性: フックの実行失敗（例外）は主処理の結果に影響を与えない

• 柔軟性: 関数ごとに異なるフックリストを hooks=[...] で指定可能

• パフォーマンス: フック未登録時のオーバーヘッドを最小化するガード条件を実装

設計根拠

コアロジックを肥大化させずにイベント駆動の拡張を可能にするため。ObserverパターンのバリエーションとしてHookBaseを定義し、各フェーズのコンテキスト（状態）をカプセル化して渡すことで、安全に状態を参照・変更できる構成とした。

コンポーネント構成

graph TD
  A[MaintenanceService] -->|操作集約| B[TaskDBBase]
  A -->|操作集約| C[BlobStorageBase]
  A -->|自動実行| D[Probabilistic Eviction]

コンポーネント責務

データフロー (GCプロセス)

sequenceDiagram
  participant Service as MaintenanceService
  participant DB as TaskDB
  participant Storage as BlobStorage

  Service->>DB: get_blob_refs()
  DB-->>Service: 有効な参照リスト (Whitelist)
  Service->>Storage: list_keys()
  Storage-->>Service: 全ファイルリスト
  Service->>Service: 差分抽出 (孤立ファイルの特定)
  Service->>Storage: delete(orphan_keys)
  Note over Service: 猶予期間 (grace_period) を考慮して削除

技術選定

非機能要件方針

• 安全性: DBレコードの削除 → Blobの削除の順序を徹底し、参照エラーを防止
• 可用性: メンテナンス中も通常のキャッシュ読み取りを妨げないロック粒度
• 観測性: 削除されたタスク数や解放された容量を統計として返却

設計根拠

運用保守の責務をアプリケーションロジックから分離するため。TaskDBとBlobStorageの両方のインターフェースを統合操作する専用サービスを設け、自動（確率的）と手動の両方から安全にクリーンアップを実行可能にした。

コンポーネント構成

graph TD
  A[beautyspot CLI] -->|Command| B[Typer App]
  B -->|Business Logic| C[MaintenanceService]
  B -->|Output| D[Rich Console]
  B -->|Dashboard| E[Dashboard App]

コンポーネント責務

データフロー

sequenceDiagram
  participant User as ユーザー
  participant CLI as CLI App
  participant Service as MaintenanceService
  participant Output as Rich Console

  User->>CLI: beautyspot gc --name my-project
  CLI->>Service: clean_garbage()
  Service-->>CLI: result (removed count, etc.)
  CLI->>Output: print summary table
  Output-->>User: formatted output

技術選定

非機能要件方針

• UX: 破壊的な操作（clear等）には対話的な確認プロンプトを表示
• 互換性: 標準出力のパイプ連携を妨げないよう、色の自動無効化に対応
• 利便性: 特定のプロジェクトだけでなく、全DBを横断的にスキャンする機能を提供

設計根拠

ライブラリのコアロジックを汚染せずにコマンドラインからの操作を提供するため。Typerを用いてCLI層を分離し、MaintenanceServiceに処理を委譲することで、ビジネスロジックの再利用とUIの関心事の分離を実現した。

コンポーネント構成

graph TD
  A[bs.Spot Factory] -->|構築| B[core.Spot]
  A -->|DI| C[TaskDBBase]
  A -->|DI| D[BlobStorageBase]
  A -->|DI| E[SerializerProtocol]
  A -->|DI| F[StoragePolicyProtocol]
  A -->|DI| G[LimiterProtocol]

コンポーネント責務

技術選定

非機能要件方針

• 結合度: core.Spot は具体的なクラス名（SQLite等）を知らず、Protocolのみに依存する
• テスト容易性: メモリ上のDBや仮装ストレージを注入することで、高速な単体テストが可能
• 拡張性: ユーザーが独自のシリアライザやストレージを自作して注入可能

設計根拠

エンドユーザーへの「ゼロ設定で動く使いやすさ」と「高度なカスタマイズ性」を両立するため。ファクトリ関数（bs.Spot）でデフォルトコンポーネントを自動ワイヤリングしつつ、個別のProtocol実装の差し替えを許容する構成とした。

コンポーネント構成

graph TD
  A[core.Spot] -->|管理要求| B[CacheManager]
  B -->|In-flight追跡| C[_inflight Dict]
  C -->|同期待機| D[threading.Event]
  C -->|非同期待機| E[asyncio.Future]

コンポーネント責務

コンポーネント責務インターフェースCacheManagerキャッシュキーごとの実行状態管理と実行のシリアライズget_or_create_inflight()_inflight実行中のタスクを保持し、後続リクエストをイベントで待機させるExecutionStatecore.Spot待機結果の受け取りとエラーの伝播cached_run()

データフロー

sequenceDiagram
  participant T1 as Thread 1 (First)
  participant T2 as Thread 2 (Second)
  participant CM as CacheManager
  participant Fn as Target Function

  T1->>CM: get_or_create(key)
  Note over CM: 新規作成 (Executor)
  T2->>CM: get_or_create(key)
  Note over CM: 既存あり (Waiter)

  T1->>Fn: execute()
  Fn-->>T1: result
  T1->>CM: set_result(key, result)
  Note over CM: Eventをセット
  CM-->>T2: notify result
  T1-->>T1: return result
  T2-->>T2: return result

技術選定

技術領域選定理由待機機構Event / FutureOS/ランタイムレベルの待機を使用し、CPU負荷（ビジーループ）を回避スコープキャッシュキー単位異なる関数の実行は妨げず、同一入力のみを直列化安全策タイムアウト & リトライ実行者がハングした場合に、待機側がデッドロックしないよう保護

非機能要件方針

• 一貫性: 実行者が成功すれば全員に結果を、失敗すれば全員に同じ例外を伝播

• 効率性: メモリリークを防ぐため、結果配布後に _inflight エントリを即座に削除

• 信頼性: 強参照 (StrongReference) で実行中のタスクを保持し、GCによる消失を防止

設計根拠

キャッシュミスの瞬間に並行リクエストが殺到した際のリソース枯渇を防ぐため。CacheManager内でIn-flight（実行中）タスクを追跡し、後続リクエストをイベント（threading.Event / asyncio.Future）で待機させる構成とした。

インターフェース

@spot.mark(
    save_blob: Optional[bool] = None,
    keygen: Optional[Union[Callable, KeyGenPolicy]] = None,
    input_key_fn: Optional[Union[Callable, KeyGenPolicy]] = None,
    version: str | None = None,
    content_type: Optional[str | ContentType] = None,
    serializer: Optional[SerializerProtocol] = None,
    save_sync: Optional[bool] = None,
    retention: RetentionSpec = None,
    hooks: Optional[Sequence[HookBase]] = None,
)
def my_func(x, y): ...

振る舞い

基本フロー

1. デコレータが対象関数をラップする
2. 呼び出し時にキャッシュキーを生成する
3. DBからキャッシュを検索する
4. ヒット時: デシリアライズして結果を返す（関数は実行しない）
5. ミス時: 関数を実行し、結果をシリアライズしてDB/Blobに保存する

sync/async 自動判定

• デコレーション時に inspect.iscoroutinefunction(fn) で判定する
• sync関数 → _execute_sync() に委譲する同期ラッパーを返す
• async関数 → _execute_async() に委譲する非同期ラッパーを返す

パラメータ詳細

エラーハンドリング

• ジェネレータ関数（isgeneratorfunction または isasyncgenfunction）を渡した場合 → デコレーション時に ConfigurationError を送出する
• cached_run 利用時に引数として関数が一つも指定されなかった場合 → ValidationError を送出する

エッジケース

• ラップされた関数の __name__, __doc__ は functools.wraps によって保持される
• @mark (括弧なし) と @mark() (括弧あり) の両方の記法をサポートする

設計判断

ユーザーが既存の関数に最小限の変更（デコレータの追加のみ）で強力なキャッシュやレート制限機能を適用できるようにするため。関数のメタデータ保持や同期・非同期の透過的な切り替えにより、開発者体験を最大化する。

インターフェース

@contextmanager
def cached_run(
    self,
    *funcs: Any,
    **kwargs: Any
) -> Iterator[Any]: ...

振る舞い

基本フロー

1. Spot インスタンスからコンテキストマネージャとして呼び出される。
2. 引数 funcs に渡された関数が0個の場合はエラーを送出する。
3. 各関数に対して、Spot.mark(**kwargs) で生成したキャッシュデコレータを適用し、ラップされた関数を生成する。
4. ラップされた関数を yield してコンテキストブロック内のユーザーコードに提供する。
5. ユーザーコード内での実行は、通常の @spot.mark 適用済み関数と同様にキャッシュ機構を経由する。
6. コンテキストブロック終了時のクリーンアップ処理は特に行わない（一時的なラッパーはスコープを抜けると破棄される）。

パラメータ詳細

戻り値（Yields）の仕様

• 1つの関数を渡した場合: ラップされた単一の callable が返る。
• 複数の関数を渡した場合: ラップされた callable のタプルが返る。

エラーハンドリング

• 引数エラー: funcs が空（0個）の場合、beautyspot.exceptions.ValidationError を送出し、コンテキストに入らない。

エッジケース

• 非同期関数やジェネレータ関数を渡した場合の挙動は、基底となる mark デコレータの制約に完全に依存する。
• 適用されるキャッシュキーは元の関数に基づくため、同名・同シグネチャの別関数が混同されないように KeyGen のスコープ規則に従う。

設計判断

デコレータを使えないケース（外部ライブラリの関数など）や、動的にキャッシュ適用を制御したいケースに対応するため。コンテキストマネージャとして提供することで、実行のスコープとリソースのライフサイクルを明確化する。

概要

@spot.mark() デコレータは同期関数と非同期（async def）関数の両方をサポートし、関数定義に応じて適切な実行・保存・キャッシュ検索フローを透過的に切り替える。

振る舞い

sync/async の自動判定

• デコレーション時に inspect.iscoroutinefunction(func) を用いて判定する。
• ランタイム時の判定オーバーヘッドを削減するため、ラッパー構築時に分岐を行う。

実行フロー

• 同期関数の場合:
• _execute_sync() に委譲する。
• キャッシュ保存（DBやBlobへのI/O）は、デフォルトでバックグラウンドのスレッドプール (ThreadPoolExecutor) にタスクを投げて非同期化される（save_sync=False の場合）。
• 非同期関数の場合:
• _execute_async() に委譲する。
• キャッシュ検索や保存処理などのI/Oバウンドな操作は、asyncio イベントループ経由でノンブロッキングに処理され、保存自体も非同期でキューに投入される。

エラーハンドリング

• ジェネレータ関数の拒否: inspect.isgeneratorfunction または inspect.isasyncgenfunction で真となるジェネレータ・非同期ジェネレータが渡された場合、サポート対象外として即座に ConfigurationError を送出する。
• 保存タスク中のバックグラウンドエラーは、同期・非同期ともに on_background_error コールバックが設定されていればそこに処理が委譲される。

エッジケース

• デコレーション後に手動で関数の性質（コルーチンかどうか）を変更するような動的な書き換えには対応しない（デコレーション時の静的な判定結果に依存する）。

設計判断

現代のPython開発では同期（I/Oバウンドでない処理）と非同期（asyncio）が混在するため。利用者が関数の種類を意識することなく同一のAPIでキャッシュを利用できる透過的なインターフェースを提供するため。

インターフェース

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() はオブジェクトによっては実行ごとに変わる可能性があるため、明示的な正規化が推奨される

設計判断

生成されたキャッシュキーが環境や実行ごとにブレることなく、常に一意であることを保証するため。ハッシュ衝突のリスクが極めて低く、暗号学的に安全で広く利用されるSHA-256を採用した。

インターフェース

@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 を送出する（実行前バリデーション）
• デフォルト値の変更: 関数のデフォルト値が変わると、同じ引数でもハッシュ値が変わる（意図的な挙動）

設計判断

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

インターフェース

class SQLiteTaskDB(TaskDBBase):
    def __init__(self, db_path: str | Path, timeout: float = 30.0): ...
    def save(self, task: TaskRecord) -> None: ...
    def get(self, cache_key: str, *, include_expired: bool = False) -> TaskRecord | None: ...

振る舞い

ライタースレッド方式

• 書き込み操作は全て _WriteTask キューに投入され、専用のバックグラウンドスレッドで直列に実行される。これにより SQLite の database is locked エラーを回避する。

読み取り並行性

• 読み取りはスレッドローカルな接続を使用し、PRAGMA query_only = ON 状態で並行して実行される。

スキーマ管理

• コンストラクタ (__init__) でスキーマ初期化を完了し、構築後のインスタンスは即座に使用可能な状態とする（RAII）。
• init_schema() は冪等であり、複数回呼び出しても安全である。
• tasks テーブルの存在を確認し、必要に応じて自動的に ALTER TABLE によるカラム追加（マイグレーション）を行う。

タイムアウトとフェイルファスト

• 全ての書き込み操作は timeout 秒以内に完了する必要がある。
• PENDING（未着手）状態: timeout を超えた場合、タスクはキューから破棄（キャンセル）され、呼び出し元に TimeoutError を返す。
• RUNNING（実行中）状態: timeout を超えた場合、sqlite3.Connection.interrupt() を用いて実行中のクエリを中断し、呼び出し元に TimeoutError を返す。これにより、ライタースレッドの恒久的なハングを防ぎ、システムの可用性を維持する。

パラメータ詳細

エラーハンドリング

• タイムアウト: TimeoutError を送出する。
• 接続失敗: sqlite3.Error をキャッチし、適切にラップして再送出する。
• シャットダウン時: ライタースレッドへの新規タスク投入を停止し、保留中のタスクを完了させてから接続を閉じる。

エッジケース

• 破損DB: DBファイルが壊れている場合は、初期化時に検知しエラーとする。
• インメモリDB: :memory: 指定時は、プロセスの生存期間中のみキャッシュが保持される。

設計判断

デフォルトのメタデータ保存先として、追加のサーバー構築が不要で、かつ高速なSQLiteを使用するため。WALモードなどを駆使して並行書き込み性能を確保する具体的な実装方針を定義した。

インターフェース

@runtime_checkable
class TaskDBCore(Protocol):
    def get(self, cache_key: str, *, include_expired: bool = False) -> TaskRecord | None: ...
    def save(self, record: TaskRecord) -> None: ...

class TaskDBBase(ABC):
    # TaskDBCore を満たしつつ、メンテナンスのデフォルト実装を提供

振る舞い

階層構造

1. TaskDBCore: キャッシュの実行に必要な最小限のメソッド定義
2. Maintenable: GCや統計取得に必要な管理用メソッドの定義
3. TaskDBBase: 共通のバリデーションや例外処理を実装する基底クラス

パラメータ詳細 (主要メソッド)

エラーハンドリング

• プロトコルに未実装のメソッドを呼び出した場合、実行時に NotImplementedError を送出する代わりに、runtime_checkable による事前チェックを推奨する。

エッジケース

• 複合実装: 複数のプロトコルを一つのクラスで実装する場合、TaskDBMaintenable 構成プロトコルとして扱う。

設計判断

データベースの実装（SQLite, Redis等）に依存しない共通の操作インターフェースを定義し、DIによるバックエンドの差し替えを可能にするため。

インターフェース

class LocalStorage(BlobStorageMaintenable):
    def __init__(self, base_dir: str | Path): ...
    def save(self, key: str, data: bytes) -> str: ...
    def load(self, location: str) -> bytes: ...

振る舞い

アトミック書き込み (save)

1. 指定ディレクトリ内に tempfile.mkstemp で一時ファイルを作成
2. データを書き込み、flush() および os.fsync() でディスク到達を保証
3. os.replace で最終的なパスへリネーム（アトミックな置換）

パストラバーサル対策 (load / delete)

• 解決後の絶対パスが base_dir の配下にあることを is_relative_to で厳密にチェックし、範囲外へのアクセスを遮断する。

パラメータ詳細

エラーハンドリング

• ファイル不在: load 時にファイルがない場合 CacheCorruptedError を送出
• 権限エラー: PermissionError 発生時は、GCでの回収に委ねるため警告ログのみ出力

エッジケース

• ディスクフル: 書き込み中に容量不足になった場合、一時ファイルを削除して OSError を送出
• Windowsパス: パス区切り文字として / と \ の両方を検証対象とする

設計判断

大きなキャッシュデータ（モデルの重み等）をローカルファイルシステムに安全かつ効率的に保存・読み込みするための具体的なインターフェースとファイル管理手法を定義するため。

インターフェース

class S3Storage(BlobStorageMaintenable):
    def __init__(self, s3_uri: str, s3_opts: dict | None = None): ...

振る舞い

URIベースの管理

• s3://bucket/prefix/key.bin 形式のURIをロケーション識別子として使用する。

大容量対応 (save)

• boto3.upload_fileobj を使用。5GBを超えるデータに対しては、自動的にマルチパートアップロードに切り替えられ、PutObjectの制限を回避する。

高速なメタデータ取得 (get_mtime)

• head_object を使用し、データ本体をダウンロードせずに最終更新時刻（LastModified）を取得する。

パラメータ詳細

エラーハンドリング

• ライブラリ不在: boto3 がインポートできない環境でインスタンス化を試みると ImportError を送出
• ネットワークエラー: botocore.exceptions.ClientError をキャッチし、状況に応じて CacheCorruptedError に変換

エッジケース

• リージョン不一致: S3クライアントの設定とバケットのリージョンが異なる場合の動作は Boto3 のデフォルト設定に依存
• 削除の冪等性: S3 は存在しないオブジェクトの削除要求に対してエラーを返さないため、常に成功として扱う

設計判断

クラウドネイティブな環境において、キャッシュデータをS3等のオブジェクトストレージに分散保存し、複数インスタンス間で安全に共有できるようにするため。

インターフェース

class StoragePolicyProtocol(Protocol):
    def should_save_as_blob(self, data: bytes) -> bool: ...

振る舞い

判定ロジック

• ThresholdStoragePolicy: len(data) が threshold を超えた場合に True を返す。
• WarningOnlyPolicy: 常に False を返すが、閾値を超えた場合にログ出力のみ行う（互換モード）。
• AlwaysBlobPolicy: 常に True を返す。

パラメータ詳細

エラーハンドリング

• ポリシー内の判定で例外が発生した場合は、安全のため False (DB保存) とみなし、エラーをログに記録する。

エッジケース

• ゼロバイト: 空のデータに対する挙動は各ポリシーの閾値設定に依存する（通常はDB保存）。
• 閾値ちょうどのサイズ: len(data) > threshold のため、閾値と等しい場合はDB保存となる。

設計判断

パフォーマンスとストレージ容量のトレードオフを最適化するため。小さなデータはDBに直接保存してI/Oを減らし、大きなデータはBlobストレージにオフロードする閾値判定の仕組みを定義した。

インターフェース

class MsgpackSerializer(SerializerProtocol, TypeRegistryProtocol):
    def dumps(self, obj: Any) -> bytes: ...
    def loads(self, data: bytes) -> Any: ...

振る舞い

シリアライズ (dumps)

1. オブジェクトの型を type(obj) で取得
2. 登録済み型またはそのサブクラス（MRO順）を探索
3. ヒットした場合、カスタムエンコーダを実行し ExtType としてパック
4. ヒットしない場合、MessagePack のデフォルト処理（または SerializationError）

デシリアライズ (loads)

1. MessagePack ストリームをパース
2. ExtType を発見した場合、コードに対応するカスタムデコーダを呼び出す

パラメータ詳細

エラーハンドリング

• 未登録型: シリアライズ時に対応するエンコーダが見つからない場合、SerializationError を送出
• デコード失敗: データ破損やコード不一致時は SerializationError を送出

エッジケース

• 動的型: 名前が同じでも ID が異なる動的生成型は、LRUキャッシュによりメモリリークを防ぎつつ効率的に処理される
• スレッド安全性: registry_generation カウンタを使用して、スレッドローカルキャッシュの整合性を維持

設計判断

JSONよりも高速でコンパクトであり、バイナリデータにもネイティブに対応できるMessagePackをデフォルトのシリアライザとして採用し、キャッシュのI/Oオーバーヘッドを最小化するため。

インターフェース

def register(
    code: int,
    encoder: Callable[[Any], Any],
    decoder: Callable[[Any], Any],
) -> Callable: ... # デコレータ形式

def register_type(
    type_class: Type,
    code: int,
    encoder: Callable[[Any], Any],
    decoder: Callable[[Any], Any],
) -> None: ...

振る舞い

1. 重複チェック: 同一コードまたは同一クラスが既に登録されていないか確認
2. CoW更新: 現在のレジストリ辞書をコピーし、新しいエントリを追加した後に参照を差し替える
3. 世代更新: _registry_generation をインクリメントし、全スレッドのLRUキャッシュを無効化対象とする

パラメータ詳細

エラーハンドリング

• コード重複: ValueError を送出し、レジストリの破損を防ぐ
• 範囲外コード: 128以上のコードを指定した場合は ValueError

エッジケース

• 継承: 基底クラスを登録すると、サブクラスも自動的にそのエンコーダを使用する（オーバーライド可能）

設計判断

標準では対応できないユーザー定義のクラス（Pandas DataFrameやPydanticモデル等）を、MessagePack経由で安全にシリアライズ・デシリアライズするための登録インターフェースを提供するため。

インターフェース

class _BackgroundLoop:
    def submit(self, coro: Coroutine) -> None: ...
    def stop(self) -> None: ...
    def is_running(self) -> bool: ...

振る舞い

1. 起動: 初回の submit 時にデーモンスレッドを作成し、asyncio.run() を開始する
2. 投入: run_coroutine_threadsafe を使用して、メインスレッドからコルーチンをイベントループへ投入
3. 待機: 投入されたタスクの完了は待たず、制御を即座に呼び出し元へ返す

パラメータ詳細

エラーハンドリング

• 投入失敗: ループ停止中にタスクが投入された場合、エラーをログ出力し無視する
• タスク内エラー: コルーチン内で発生した例外は、on_background_error コールバックで処理される

エッジケース

• 多重起動: すでにスレッドが実行中の場合は、既存のスレッドを再利用する

設計判断

関数のメイン処理をブロックすることなく、背後で安全にキャッシュデータを永続化するため。専用のイベントループにより、I/O待ちによるパフォーマンス低下を防ぐ。

インターフェース

def flush(timeout: float | None = None) -> bool: ...

@spot.mark(save_sync=False)
def my_func(): ...

振る舞い

同期保存 (save_sync=True)

• 関数終了後、DBおよびBlobへの保存が完了するまで呼び出し元をブロックする。

非同期保存 (save_sync=False)

• 保存処理を BackgroundLoop に委譲し、即座に関数の戻り値を返す。

フラッシュ (flush)

• _inflight タスク（保存中）のリストを確認し、それら全てが完了するまで、またはタイムアウトまで待機する。

パラメータ詳細

エラーハンドリング

• タイムアウト: flush がタイムアウトした場合、False を返し、一部のデータが未保存である可能性を通知する。

エッジケース

• コンテキスト終了: with spot: 終了時に自動的に flush が呼ばれ、プロセス終了前のデータ保存を確実にする。

設計判断

スクリプトの終了時や、確実にキャッシュを永続化してから次の処理に進みたいケース（バッチ処理等）において、バックグラウンドの非同期保存タスクの完了を待機し、データロストを防ぐ制御手段を提供するため。

インターフェース

class LifecyclePolicy:
    def add_rule(self, pattern: str, retention: Any) -> None: ...
    def resolve_with_fallback(self, func_name: str) -> float | None: ...

振る舞い

1. 順次照合: 登録された順にルールを走査する

2. パターンマッチ: fnmatch.fnmatch を使用し、関数名がパターンに合致するか判定

3. 二段階解決:

   1. 最初に「完全修飾名 (module.qualname)」で照合

   2. マッチしなければ「短縮名 (qualname)」で照合

4. 結果返却: 最初にマッチしたルールの保持期間を秒数に変換して返す

パラメータ詳細

パラメータ例説明pattern"my_mod.*", "*_test"Glob形式のパターンretention"30d", 3600保持期間の定義

デフォルト保持期間

• default_retention パラメータで、どのルールにもマッチしない場合のデフォルト保持期間を指定できる
• LifecyclePolicy.default() のデフォルト値は "30d"（30日）
• None を指定すると無期限保持（従来互換）

エラーハンドリング

• マッチなし: 全てのルールにマッチしない場合は、default_retention で指定された保持期間を返す（デフォルト: 30日）

エッジケース

• 重複パターン: 先に登録されたルールが優先される。

設計判断

関数名ごとのパターンマッチを用いて、特定の関数群に対して一括でキャッシュの有効期限（Retention）を適用できる柔軟なルールベースのライフサイクル管理を実現するため。

インターフェース

def parse_retention(val: Any) -> float | None: ...

振る舞い

文字列パース

• "7d" (7日), "12h" (12時間), "30m" (30分), "10s" (10秒) 形式を秒数に変換する。大文字小文字は区別しない。

数値・オブジェクト

• int, float: 秒数としてそのまま扱う。
• timedelta: total_seconds() を取得。
• None: ポリシーに従う（または無期限）を意味する。

パラメータ詳細 (単位)

エラーハンドリング

• 不正な形式: パーサが理解できない形式の場合は ValidationError を送出する。
• 負の値: 過去の時間は指定できず、ValidationError となる。

エッジケース

• FOREVER: 特別な定数 Retention.FOREVER (無限大の秒数) を提供し、ポリシーに関わらず永続化を指示できる。

設計判断

ユーザーが直感的に理解しやすい文字列（例: '7d', '12h'）で有効期限を指定できるようにし、内部で秒数に正規化して統一的に処理するため。

インターフェース

class TokenBucket(LimiterProtocol):
    def consume(self, cost: float = 1.0) -> None: ...
    async def consume_async(self, cost: float = 1.0) -> None: ...

振る舞い

GCRAアルゴリズム

• 各リクエストに対して「次回実行可能な理論時刻 (TAT: Theoretical Arrival Time)」を計算・更新する。
• 現在時刻が TAT - 許容バースト 以前の場合、リクエストを拒否または待機させる。

同期 vs 非同期

• consume: 待機が必要な場合は time.sleep() でブロック。
• consume_async: 待機が必要な場合は asyncio.sleep() で非占有待機。

パラメータ詳細

エラーハンドリング

• 即時拒否モード: 待機を許容しない設定でレート超過した場合、RateLimitError (ValueErrorのサブクラス) を送出する。

エッジケース

• 高コストリクエスト: max_burst を超えるコストを持つ単一リクエストは、常に拒否される。
• アイドル時間: 長時間リクエストがない場合も、TAT は現在時刻より過去に一定以上離れないよう補正される（過度なバーストの防止）。

設計判断

外部APIのレート制限（例: 1分間に100リクエスト）を正確に守るため。GCRA（Generic Cell Rate Algorithm）により、バーストを許容しつつ、滑らかで厳密な流量制御を実現する。

インターフェース

class HookBase:
    def pre_execute(self, ctx: PreExecuteContext) -> None: ...
    def on_cache_hit(self, ctx: CacheHitContext) -> None: ...
    def on_cache_miss(self, ctx: CacheMissContext) -> None: ...

振る舞い

1. フック呼出: キャッシュエンジンの各ステート（実行前、ヒット、ミス）で登録されたフックを順番に実行する
2. スレッド安全化: ThreadSafeHookBase を継承した場合、メタクラスが自動的に各メソッドを with self._lock: で包む

パラメータ詳細 (Context)

エラーハンドリング

• フック内例外: フックの実行中に発生した例外はキャッチされ、エラーログとして出力されるが、主処理（関数の実行結果）は中断されない。

エッジケース

• フックの順序: hooks=[h1, h2] と指定した場合、h1 -> h2 の順で実行される。

設計判断

キャッシュヒット時のログ出力や、LLMのトークン消費量の集計など、メインのビジネスロジックに手を加えずにカスタム処理を介入させるための、安全な拡張ポイント（フック）を提供するため。

インターフェース

class MaintenanceService:
    def clean_garbage(self, grace_period: int = 3600) -> GarbageStats: ...
    def prune(self, days: int, func_name: str | None = None) -> int: ...
    def clear(self, func_name: str | None = None) -> int: ...

振る舞い

ガベージコレクション (clean_garbage)

1. DB Flush: 保存中のタスクをDBへ反映させる
2. 期限切れ削除: delete_expired() でDBから古いタスクを除去
3. 孤立Blobスキャン: DB内の全 blob_key とストレージ内の全ファイルを比較
4. 物理削除: 参照のないBlobのうち、作成から grace_period 以上経過したものを削除
5. 構造清掃: ストレージ内の空ディレクトリを削除

パラメータ詳細

エラーハンドリング

• 削除失敗: 個別のファイル削除失敗は警告ログに留め、全体の処理は継続する。
• DBロック: メンテナンス中にDBがロックされた場合は、タイムアウトまで待機し失敗させる。

エッジケース

• 大規模ストレージ: Blobの列挙はジェネレータで行い、メモリ使用量を抑制する。
• 名前空間: clear(func_name) は前方一致ではなく、完全一致（または glob）で判定する。

設計判断

長期間の運用で蓄積される不要なキャッシュデータや期限切れデータを、手動または自動で安全に削除・整理し、システムをクリーンな状態に保つためのメンテナンスAPIを定義するため。

インターフェース

beautyspot list [--db DB_PATH]
beautyspot gc [--name PROJECT_NAME] [--force]
beautyspot stats
beautyspot ui

振る舞い

1. コンテキスト解決: --db 指定がない場合、デフォルトの .beautyspot/ ディレクトリを探索する
2. コマンド実行: MaintenanceService または Spot インスタンスを生成し、対応するメソッドを呼び出す
3. フォーマット出力: Rich ライブラリを使用して、結果をテーブルやプログレスバーで表示する

サブコマンド詳細

エラーハンドリング

• DB不在: 指定されたパスにDBがない場合は、エラーメッセージを表示して終了する。
• 権限不足: ファイル削除権限がない場合は、スキップされた旨を表示する。

エッジケース

• 非対話環境: CI等での実行を考慮し、色の無効化や確認プロンプトのスキップ（--force）に対応する。

設計判断

運用者がPythonコードを書くことなく、CLIから手軽にキャッシュの統計情報確認やガベージコレクションを実行できるようにし、運用保守のコストを下げるため。

インターフェース

def Spot(
    name: str = "default",
    storage_path: str | Path | None = None,
    serializer: SerializerProtocol | None = None,
    limiter: LimiterProtocol | None = None,
    # ...その他の依存
) -> core.Spot: ...

振る舞い

1. パス解決: storage_path が未指定の場合、.beautyspot/ 以下のプロジェクト名ディレクトリを使用する
2. DB初期化: SQLiteTaskDB を生成し、マイグレーションを実行
3. ストレージ構成: URI（s3://等）を判定し、適切な BlobStorage 実装を生成
4. インスタンス化: 全てのコンポーネントを core.Spot のコンストラクタに注入して返す

パラメータ詳細

エラーハンドリング

• ディレクトリ作成失敗: 権限等の理由でストレージディレクトリが作成できない場合は、早期に OSError を送出する。

エッジケース

• グローバルシングルトン: 同じ name で複数回呼び出した場合も、原則として新しいインスタンスを返すが、DBファイルへの接続は共有される（SQLiteのWALモードを活用）。

設計判断

Spotクラスの初期化において、DIコンテナとして機能するファクトリを提供し、ユーザーが複雑なコンポーネント構成を意識することなく、シンプルにライブラリを利用開始できるようにするため。

インターフェース

class CacheManager:
    def herd_sync(
        self, key: str, serializer: Optional[SerializerProtocol] = None
    ) -> Generator[HerdWaitResult, None, None]: ...

    async def herd_async(
        self,
        key: str,
        serializer: Optional[SerializerProtocol],
        loop: asyncio.AbstractEventLoop,
        executor: Any,
    ) -> AsyncGenerator[HerdWaitResult, None]: ...

振る舞い

同時実行制御

1. キャッシュキーをキーとした _inflight 辞書をチェックする
2. 存在しない場合: HerdWaitResult を新規作成し、自分が「実行者 (Executor)」となる
3. 存在する場合: 既存の HerdWaitResult を返し、自分は「待機者 (Waiter)」となる
4. 完了通知: 実行者が処理を終えたら、HerdWaitResult の Event (または Future) をセットし、結果を共有する
5. 自動クリーンアップ: with または async with ブロックを抜ける際、実行者は自動的に notify_and_cleanup_inflight を呼び出し、インフライト状態を解除する。これにより例外発生時も状態が残留しないことが保証される。

強参照によるインフライト状態の保持

目的

実行中のタスク状態（イベント・結果・Future）が GC によって消失しないよう、 _inflight 辞書を通じて強参照で保持する。WeakRef は使用しない。

データ構造

_inflight 辞書はキャッシュキーをキーとし、以下の3要素タプルを値として保持する:

_inflight: dict[str, tuple[threading.Event, list[asyncio.Future], list]]

ライフサイクル

1. 作成: herd_sync / herd_async コンテキスト開始時に _inflight にキーが存在しない場合、 _inflight_lock を保持した状態で新規タプルを挿入する
2. 保持: 実行者が処理を完了するまで、_inflight 辞書がタプルへの唯一の管理参照を保持する。 待機者はロック取得時にタプル要素への参照を取得するが、_inflight エントリが正規の所有者である
3. 解放: コンテキスト終了（__exit__ / __aexit__）時に notify_and_cleanup_inflight で以下の順序で解放する: a. _inflight_lock を取得し、エントリの同一性を event の identity (is) で確認する b. 辞書からエントリを削除する（del _inflight[cache_key]） c. ロックを解放した後、event.set() で同期待機者に通知する d. futures リスト内の各 asyncio.Future に結果またはエラーを伝播する

不変条件

• _inflight 辞書への挿入・削除は常に _inflight_lock の保護下で行う
• 1つのキャッシュキーに対して _inflight 内には高々1つのエントリしか存在しない
• エントリの削除は、挿入時の event と同一オブジェクト（is 比較）を持つスレッドのみが行える
• result_box への書き込みは実行者スレッドのみが行い、待機者は読み取り専用とする
• futures リストへの追加は _inflight_lock の保護下でのみ行う

GC安全性

_inflight 辞書は CacheManager インスタンスの属性であり、CacheManager が 生存している限り、全てのインフライトエントリは GC の対象にならない。 CacheManager 自体は Spot インスタンスが所有するため、with spot: ブロック内での 安全性が保証される。

パラメータ詳細

エラーハンドリング

• 実行者失敗: 実行者が例外を投げた場合、待機者全員にも同じ例外が伝播される。
• タイムアウト: タイムアウト時は待機を解除し、自らが実行者となって再試行（またはエラー）を試みる。

エッジケース

• 非同期混在: 同一キーに対して同期実行と非同期実行が混在する場合も、スレッドセーフなロックにより一つの実行に絞り込まれる。

設計判断

キャッシュミスの際に、複数のスレッド/プロセスが同時に重い関数を実行してしまうのを防ぎ、最初の1つの実行結果を他の要求にも共有させることで、システムの過負荷を回避するため。

インターフェース

class BlobStorageBase(ABC):
    @abstractmethod
    def save(self, key: str, data: ReadableBuffer) -> str: ...
    @abstractmethod
    def load(self, location: str) -> bytes: ...
    @abstractmethod
    def delete(self, location: str) -> None: ...
    @abstractmethod
    def list_keys(self) -> Iterator[str]: ...
    @abstractmethod
    def get_mtime(self, location: str) -> float: ...

振る舞い

• save: データを永続化し、一意な識別子（パスやURI）を返す。
• load: 識別子を基にバイトデータを復元する。
• delete: 識別子を基にデータを削除する。存在しない場合は無視する（冪等）。
• list_keys: メンテナンス用に、保存されている全オブジェクトの識別子を列挙する。
• get_mtime: 最終更新時刻を POSIX タイムスタンプで返す。

パラメータ詳細

エラーハンドリング

• 実装クラスは、データの欠損やアクセス不可時に CacheCorruptedError を送出すべきである。

エッジケース

• バイナリ互換: ReadableBuffer を受け入れることで、memoryview 等を使用したゼロコピー書き込みを可能にする。

設計判断

ローカルファイルやS3といった具体的なストレージ実装に依存しない抽象インターフェースを定義し、ユーザーが要件に合わせて独自の保存先を簡単に実装・注入できるようにするため。

目的

@spot.mark() はユーザーが最も頻繁に使う公開APIであり、キャッシュの正確性・透過性・拡張性の基盤となる。デコレーションによって元の関数の挙動やメタデータが損なわれると、ユーザーコードのデバッグや型チェックに支障をきたすため、ラッパーの透過性を厳密に検証する。

検証観点

• 正常系: 同一引数での2回目呼び出しでキャッシュヒットし、元の関数が再実行されないこと
• Blobモード: save_blob=True 指定時にDB直接保存ではなくBlobストレージ経由で保存されること
• ラッパー透過性: デコレーション後も __name__, __doc__, inspect.signature が元の関数と一致すること
• シリアライザ差し替え: serializer= パラメータでデフォルトの MsgpackSerializer をカスタム実装に置換できること
• キャッシュ無効化: version= パラメータを変更するとキャッシュキーが変わり、既存キャッシュがヒットしなくなること

目的

cached_run はデコレータを直接付与できない外部ライブラリ関数にキャッシュを適用する唯一の手段であり、このAPIの不具合はサードパーティ統合シナリオ全体に影響する。戻り値の型が関数の数で変わるスマートリターン仕様は、誤実装すると型安全性を損なうため重点的に検証する。

検証観点

• 単一関数: 1つの関数を渡した場合、結果がそのまま（タプルでなく）返ること
• 複数関数: 2つ以上の関数を渡した場合、結果がタプルで返ること
• バリデーション: 関数を0個渡した場合に ValidationError が送出されること
• 型推論: mypy / pyright で戻り値の型が正しく推論されること
• キャッシュ動作: コンテキスト内で同一引数の再呼び出しがキャッシュヒットすること

目的

beautyspot は同期・非同期の両方の関数を透過的にキャッシュするが、asyncio 固有のイベントループ制約（スレッドをまたぐコルーチン実行、例外伝播のタイミング差異）により、同期版とは異なる不具合が発生しやすい。非同期パスの堅牢性を独立して検証する。

検証観点

• 自動判定: inspect.iscoroutinefunction() により同期/非同期が正しく識別され、適切なラッパーが適用されること
• 例外伝播: async 関数内で送出された例外が、await 側に正しく伝播し、キャッシュに保存されないこと
• 非同期 thundering herd: 同一キーへの複数の concurrent な await が1回の実行結果を共有すること
• 非同期保存: save_sync=False 時に _BackgroundLoop 経由でキャッシュ保存が非同期実行されること

目的

キャッシュキーはキャッシュの同一性判定の基盤であり、ハッシュが不安定だとキャッシュミスの頻発（性能劣化）や誤ヒット（データ不整合）を引き起こす。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")) のようにデコレータ経由で戦略が正しく適用されること

目的

SQLiteTaskDB はキャッシュメタデータの永続化を担う中核コンポーネントであり、DB の不整合はキャッシュの消失や重複実行を引き起こす。WALモード・専用ライタースレッドという独自アーキテクチャの信頼性を保証する。

検証観点

• スキーマ初期化: 新規DBファイルに対してテーブルとインデックスが正しく作成されること。既存DBへの自動マイグレーション（content_type, version, result_data, func_identifier, expires_at カラム追加）が冪等に動作すること
• CRUD操作: タスクの作成・取得・更新・削除が正しく動作し、存在しないキーへのアクセスが適切にハンドルされること
• 読み取り接続リカバリ: スレッドローカルな読み取り接続がクローズされた場合に自動的に再作成され、接続リークが発生しないこと
• ライタースレッドのタイムアウト: 書き込みキューのタイムアウト時に適切なエラーが返り、ライタースレッドがデッドロックしないこと
• GC耐性: ガベージコレクション実行後もDBファイルが存続し、有効なタスクが失われないこと

目的

TaskDBCore / TaskDBBase のプロトコル階層は、サードパーティによるカスタムDB実装（Redis、PostgreSQL 等）の差し替えを可能にする拡張ポイントである。インターフェース契約が不明確だと、カスタム実装が実行時に予期しないエラーを起こす。

検証観点

• インターフェース準拠: TaskDBCore の必須メソッド（save, load, delete 等）を実装したクラスが isinstance チェックをパスすること
• TaskDBBase 拡張: TaskDBBase がメンテナンス系メソッド（prune, stats 等）のデフォルト実装を提供し、サブクラスが必須メソッドのみの実装で動作すること
• デフォルト動作: メンテナンスメソッドのデフォルト実装が安全なno-op（空リスト返却等）であること
• カスタム実装の注入: bs.Spot(db=CustomDB()) でプロトコル準拠のカスタムDBが正常に動作すること

目的

LocalStorage はBlobデータのファイルシステム永続化を担い、並行書き込み時のデータ破損やパストラバーサルによるセキュリティ脆弱性が発生しうる。アトミック書き込みとセキュリティバリデーションの正確性を保証する。

検証観点

• ワークスペース初期化: base_dir が存在しない場合に自動作成され、.gitignore が配置されること
• アトミック書き込み: tempfile.mkstemp → fsync → os.replace のフローで、書き込み中のクラッシュや並行アクセスでファイルが破損しないこと
• 並行書き込み一貫性: 複数スレッドから同一キーへの同時書き込みで、最終状態が正しい完全なデータであること
• パストラバーサル防止: キーに .. や / を含む場合に ValidationError が送出され、base_dir 外へのアクセスが不可能であること。load() でも is_relative_to 検証が機能すること
• 一時ファイルクリーンアップ: clean_temp_files() が猶予期間超過の .spot_tmp ファイルを削除し、猶予期間内のファイルは保持すること
• 冪等削除: delete() が存在しないキーに対してもエラーを送出しないこと

目的

S3Storage はクラウド環境での大規模Blob保存を担い、ネットワーク障害・認証エラー・バケット不在などオンプレミスにはない障害モードが存在する。boto3 オプショナル依存のガード処理も含め、クラウドストレージ統合の信頼性を検証する。

検証観点

• 基本CRUD: S3互換ストレージへの save / load / delete / list_keys が正しく動作すること
• オプショナル依存ガード: boto3 がインストールされていない環境で import 時にわかりやすいエラーメッセージが表示されること
• エラーハンドリング: バケット不在、権限不足、ネットワークエラー時に適切な例外が送出されること
• 注記: boto3 のモック戦略（moto 等）を使用したテストの実装を推奨

目的

ストレージポリシーは「データをDB直接保存するか、Blobストレージに分離するか」を決定する戦略レイヤーである。閾値判定の誤りはDBの肥大化（性能劣化）や不要なBlob分離（オーバーヘッド増加）を招く。3種のポリシー実装がそれぞれの契約を正しく満たすことを検証する。

検証観点

• ThresholdStoragePolicy: 閾値未満のデータで False、閾値以上のデータで True を返すこと。境界値（ちょうど閾値サイズ）での挙動が明確であること
• WarningOnlyPolicy: 常に False を返しDB直接保存を選択すること。ただし閾値超過時に WARNING レベルのログが出力されること
• AlwaysBlobPolicy: データサイズに関係なく常に True を返すこと
• Spot 統合: @spot.mark(save_blob=True/False) の明示指定がポリシー判定より優先されること。save_blob=None（デフォルト）時にポリシーの should_save_as_blob() が呼ばれること

目的

MsgpackSerializer はキャッシュデータの永続化形式を決定する。シリアライズの不具合はデータ消失（デシリアライズ不能）やサイレントなデータ劣化（精度低下等）に直結する。スレッドセーフ性の欠如はマルチスレッド環境での競合状態を引き起こす。

検証観点

• ラウンドトリップ: プリミティブ型（int, float, str, bytes, None, bool）と基本コレクション（list, dict）が dumps → loads で元の値と一致すること
• Pydantic モデル: Pydantic モデルが dict に変換されてシリアライズされ、デシリアライズ後に元のモデルが復元されること
• numpy 配列: ndarray の shape, dtype, 値が保持されること。float64 等の精度が劣化しないこと
• スレッドセーフ LRU キャッシュ: サブクラス解決のキャッシュがスレッドローカルであり、複数スレッドからの同時アクセスで競合しないこと
• ExtType 拡張: カスタム型が ExtType (code 0-127) で正しく登録・解決されること

目的

カスタム型登録はユーザー定義クラスのキャッシュを可能にする拡張ポイントである。登録の不備は SerializationError によるキャッシュ保存失敗を引き起こし、ユーザーの既存コードとの統合を阻害する。デコレータ方式と命令方式の両方の登録パスを検証する。

検証観点

• デコレータ登録: @spot.register(code=N, encoder=..., decoder=...) でクラスが登録され、そのインスタンスのシリアライズ/デシリアライズが正常に動作すること
• 命令的登録: spot.register_type(MyClass, code=N, ...) でも同等の登録が行われること
• Pydantic factory デコーダ: Pydantic モデルの model_validate をデコーダとして使用する場合に、バリデーション付きの復元が正しく動作すること
• ネスト構造: カスタム型を含む dict、カスタム型のリスト、カスタム型をフィールドに持つカスタム型など、複雑な入れ子構造が正しくエンコード/デコードされること
• code 衝突: 同一 code を重複登録した場合の挙動が明確であること

目的

_BackgroundLoop はデーモンスレッドで asyncio イベントループを駆動し、非同期キャッシュ保存を処理する。スレッド間のコルーチン受け渡しは競合状態やデッドロックが発生しやすく、シャットダウン時のタスク消失はデータロスに直結する。

検証観点

• 保存の正確性: submit(coro) で投入したコルーチンが正しく実行され、結果がDBとストレージに反映されること
• 直列化保証: 同一キーへの保存が投入順に処理され、最終状態が最後に投入されたデータであること
• ゾンビスレッド防止: シャットダウン後にアクティブタスクが drain_timeout 秒以内に完了すること。タイムアウト後は強制終了されること
• atexit 安全網: プロセス終了時に atexit ハンドラが発火し、未完了タスクの drain が試行されること
• 新規受付停止: シャットダウン後の submit() 呼び出しが受け付けられないこと

目的

save_sync パラメータと flush / drain メカニズムは、キャッシュ保存のレイテンシとデータ安全性のトレードオフをユーザーが制御する手段である。save_sync=False 使用時にデータが失われないことと、コンテキストマネージャによる確実なフラッシュを保証する。

検証観点

• save_sync=True（デフォルト）: キャッシュ保存が呼び出しスレッドで同期的に完了し、関数リターン時点でデータが永続化されていること
• save_sync=False: キャッシュ保存がバックグラウンドに委譲され、関数がレイテンシなしでリターンすること。保存が最終的に完了すること
• flush(): spot.flush(timeout) 呼び出しで全ペンディング保存が完了するまで待機すること。タイムアウト時の挙動が明確であること
• コンテキスト exit での drain: with spot: ブロック終了時に未完了の保存が自動的に drain されること
• コンテキストマネージャの再利用: 同一 spot インスタンスが複数の with ブロックで再利用でき、各ブロック終了時に適切に drain されること
• バックグラウンド保存失敗: 非同期保存が例外を送出した場合に on_background_error コールバックが呼ばれ、メインスレッドには影響しないこと

目的

LifecyclePolicy はキャッシュデータの保持期間を関数名パターンで制御する。パターンマッチングの不備は、重要なキャッシュの意図しない削除（データロス）や不要なキャッシュの蓄積（ディスク圧迫）を引き起こす。

検証観点

• パターンマッチング: glob パターン（"train_*", "*.preprocess" 等）がルールの func_pattern として正しく機能し、マッチした関数に対して指定の Retention が適用されること
• ルール優先順位: 複数ルールがマッチした場合に、リスト順（先勝ち or 後勝ち）でルールが決定されること
• resolve_with_fallback: 完全修飾名（module.qualname）でルールが見つからない場合に、短縮名（qualname のみ）でフォールバック検索が行われること
• デフォルト保持期間: どのルールにもマッチしない関数に対して default_retention で指定された保持期間（デフォルト: 30日）が適用されること
• 無期限保持の互換性: default_retention=None を指定した場合に無期限保持（None）が返されること

目的

Retention はキャッシュの有効期間をユーザーフレンドリーな形式で指定する値オブジェクトである。パースの不備は意図しない保持期間（例: "7d" を 7秒と誤解釈）を招き、重要なキャッシュの早期削除やディスクの際限ない肥大化に繋がる。

検証観点

• 文字列パース: "7d" → 7日、"12h" → 12時間、"30m" → 30分、"10s" → 10秒として正しく解釈されること
• timedelta 入力: timedelta(days=7) がそのまま保持期間として受け入れられること
• 秒数入力: 整数・浮動小数点数が秒として解釈されること
• FOREVER シングルトン: Retention.FOREVER が無期限保持を表し、シングルトンであること（is 比較が成立）
• バリデーション: 負値（"-1d"）やゼロ（"0s"）が ValidationError を送出すること。不正な形式（"abc", "" 等）も拒否されること

目的

TokenBucket はAPI呼び出しやリソースアクセスのレート制限を実現する。レートリミッターの不具合はAPIの過負荷（制限が甘い場合）やスループットの不必要な低下（制限が厳しすぎる場合）を招く。GCRA アルゴリズムのスムーズなレート制御を検証する。

検証観点

• 初期化バリデーション: rate ≤ 0 や capacity ≤ 0 などの不正パラメータが拒否されること
• max_cost 超過拒否: 1回のリクエストコストがバケット容量を超える場合に即座に拒否されること（無限待機にならないこと）
• GCRA 待機動作: バケットが空の状態でリクエストした場合に、トークン補充まで適切な時間だけ待機すること。待機時間がレートに基づいて正確であること
• バースト許容: 容量分のリクエストがバーストで処理でき、超過分からスロットリングが開始されること

目的

Hook システムはキャッシュライフサイクルへのユーザー拡張ポイント（ロギング、メトリクス収集、監査等）であり、フック内の不具合がメインの関数実行に影響を与えないことが最重要の契約である。また ThreadSafeHookBase の自動ロック機構の正確性を保証する。

検証観点

• ライフサイクル呼び出し順: キャッシュミス時に pre_execute → 関数実行 → on_cache_miss の順でフックが呼ばれること。キャッシュヒット時に pre_execute → on_cache_hit の順で呼ばれること
• コンテキスト情報: 各フックに渡されるコンテキスト（PreExecuteContext, CacheHitContext, CacheMissContext）が正しい情報（func_name, args, result 等）を含むこと
• 例外隔離: フック内で例外が発生しても、関数の実行結果には影響せず、ERROR ログにのみ記録されること
• 状態保持: フックインスタンスが呼び出し間で状態（カウンタ等）を保持できること
• ThreadSafeHookBase: __init_subclass__ によりユーザー定義メソッドが自動的に RLock でラップされ、複数スレッドからの同時呼び出しで競合状態が発生しないこと

目的

MaintenanceService は CLI やダッシュボードからのシステム管理操作を仲介するサービス層である。タスク詳細の表示ミスは運用者の誤判断を招き、メンテナンス操作の不備はデータの意図しない削除に繋がる。

検証観点

• タスク詳細取得: 存在するタスクIDに対して正しいメタデータ（func_name, input_key, result, created_at 等）が返却されること
• 存在しないタスク: 不在のタスクIDに対して None が返却され、例外が送出されないこと
• 統計情報: キャッシュの件数、サイズ、関数ごとの分布など統計情報が正確に算出されること
• クリア操作: 指定条件に合致するタスクのみが削除され、他のタスクが影響を受けないこと
• GC 操作: 有効期限切れタスクの削除と孤立Blobファイルのクリーンアップが正しく連動すること

目的

CLI はユーザーがキャッシュの状況確認・管理を行う主要インターフェースであり、コマンドの不具合はユーザー体験と運用効率に直接影響する。CliRunner によるコマンド実行と出力の正確性を E2E で検証する。

検証観点

• list コマンド: キャッシュ済みタスクの一覧が正しく表示されること。DBが空の場合に適切なメッセージが表示されること
• show コマンド: 指定タスクの詳細情報（func_name, input_key, created_at, result サイズ等）が正しく表示されること
• stats コマンド: キャッシュ統計（総件数、関数別件数、ストレージ使用量等）が正確に表示されること
• clear コマンド: 確認プロンプト後にキャッシュが削除されること。--force フラグでプロンプトがスキップされること
• gc / prune コマンド: 有効期限切れタスクの削除と孤立Blobの清掃が正しく実行されること
• E2E パイプライン: @mark でキャッシュ保存 → beautyspot list で確認 → beautyspot clear で削除、という一連のワークフローが正常に動作すること
• エラー時の終了コード: 不正な引数やDB不在時に非ゼロの終了コードが返ること

目的

bs.Spot() ファクトリ関数は全コンポーネントの DI 配線を担う唯一のパブリックエントリポイントであり、デフォルト構成の正確性とカスタム実装の差し替え可能性がシステム全体の柔軟性と正確性を決定する。

検証観点

• デフォルト構成: 引数未指定時に SQLiteTaskDB, LocalStorage, MsgpackSerializer, TokenBucket, WarningOnlyPolicy が自動注入されること。ワークスペースディレクトリ（.beautyspot/）が自動作成されること
• カスタム DB 注入: TaskDBBase / TaskDBCore プロトコル準拠のカスタムDBを db= で注入し、正常にキャッシュ操作が行えること
• カスタム Storage 注入: BlobStorageBase 準拠のモック Storage を storage_backend= で注入し、Blob保存が委譲されること
• カスタム Serializer 注入: SerializerProtocol 準拠のカスタム Serializer を注入し、シリアライズ処理が差し替わること
• 型推論: bs.Spot() の戻り値型が pyright / mypy で正しく推論されること
• Protocol 不準拠の拒否: 必須メソッドを欠くオブジェクトを注入した場合に型チェックエラーまたは実行時エラーが発生すること

目的

Thundering Herd Protection は、同一キーへの並行リクエストが一斉に関数を実行する「Thundering Herd」問題を防ぐ。この保護が不完全だと、重い計算やAPI呼び出しが不要に多重実行され、リソース浪費やレートリミット超過を招く。並行性バグはテスト困難であるため、複数の観点から網羅的に検証する。

検証観点

• 同期並行: 複数スレッドが同一キーで同時にキャッシュミスした場合、関数が1回のみ実行され、全スレッドが同じ結果を受け取ること
• 非同期並行: 複数の asyncio.Task が同一キーで同時にキャッシュミスした場合も、関数が1回のみ実行されること
• 例外伝播: 実行者（executor）の関数が例外を送出した場合、全待機スレッド/タスクに同じ例外が伝播すること。例外後に _inflight エントリがクリーンアップされること
• タイムアウト: 待機が HERD_TIMEOUT（300秒）を超過した場合にタイムアウト処理が発動し、無限待機にならないこと
• リトライ: HERD_MAX_RETRIES（3回）の範囲でリトライが行われ、上限超過で最終エラーが返ること
• CacheManager モック: _inflight 辞書の状態遷移（エントリ追加→結果セット→エントリ削除）が正しい順序で行われること

目的

BlobStorageBase は全ストレージバックエンド（LocalStorage, S3Storage, サードパーティ）が 準拠すべき抽象契約を定義する。この契約が正しく機能しないと、キャッシュデータの 保存・復元・削除・メンテナンス（GC）の全てが破綻する。 LocalStorage を具象実装として使い、インターフェース契約を網羅的に検証する。

検証観点

• save 基本動作: データを永続化し、一意な識別子（文字列）を返すこと
• ReadableBuffer 互換: bytes, bytearray, memoryview の全てを受け入れること（ゼロコピー書き込み）
• save 上書き: 同一キーに再保存するとデータが更新されること
• 空データ: 空バイト (b"") を正常に保存・復元できること
• load ラウンドトリップ: save した内容を load で完全に復元できること
• load 欠損時エラー: 存在しないロケーションへの load は CacheCorruptedError を送出すること
• delete 基本動作: 保存済みデータを削除し、以後の load がエラーになること
• delete 冪等性: 存在しないロケーションや二重削除でエラーにならないこと（冪等）
• list_keys 空: データ未保存時は空イテレータを返すこと
• list_keys 列挙: save したアイテムが list_keys に含まれること
• list_keys 削除後: delete 後は list_keys に含まれないこと
• get_mtime 正確性: POSIX タイムスタンプ（float）を返し、保存直後は現在時刻に近いこと
• get_mtime 欠損時エラー: 存在しないロケーションでエラーを送出すること

実装概要

Spot.mark() メソッドが本仕様の中核。二段階デコレータファクトリとして、 オプションを受け取る外側の mark() と、関数をラップする内側の decorator() で構成される。 sync/async の判定は inspect.iscoroutinefunction() でデコレーション時に行い、 同期関数は _execute_sync()、非同期関数は _execute_async() に委譲する。 functools.wraps(fn) により元関数のメタデータ（__name__, __doc__, __module__, __qualname__）を保持する。

設計判断

二段階デコレータファクトリの採用

@mark() （括弧あり）と @mark（括弧なし）の両方をサポートするため、 引数の型で分岐するパターンを採用した。第一引数が callable なら括弧なし、 そうでなければ括弧ありと判定する。

sync/async 分岐のタイミング

デコレーション時に判定する方式を採用。呼び出し時に毎回 inspect する方式と比較し、 ランタイムオーバーヘッドがゼロになる利点がある。ただしデコレーション後に 関数の性質が動的に変わるケースには対応できない（実用上問題なし）。

ジェネレータ関数の拒否

inspect.isgeneratorfunction() と inspect.isasyncgenfunction() の 両方をチェックし、ConfigurationError を送出する。 ジェネレータの戻り値はイテレータであり、キャッシュの意味論と矛盾するため。

実装メモ

• inspect.signature の保持は functools.wraps が設定する __wrapped__ 属性に依存する
• オプションの解決は _resolve_settings() で Spot レベルのデフォルト → 関数レベルのオーバーライドの順で行われる
• keygen パラメータが指定された場合、KeyGenPolicy.bind(fn) でシグネチャにバインドされたキー生成関数に変換される

TODO / 技術的負債

• デコレータの多重適用（@mark を2回付ける）時の検出・警告が未実装

実装概要

Spot.cached_run() はコンテキストマネージャとして実装。 渡された関数群を内部で mark() と同等のラッピングを行い、 コンテキスト内で呼び出すとキャッシュが効く一時的なラッパーを返す。

設計判断

スマートリターンの型分岐

単一関数の場合は結果を直接返し、複数関数の場合はタプルで返す。 これにより wrapped_fn = spot.cached_run(fn) のように自然に書ける。 0個の場合は ValidationError で早期失敗させる。

コンテキストマネージャパターン

@contextmanager デコレータを使用。__enter__ でラップ済み関数を返し、 __exit__ で後処理（drain 等）は with spot: に委譲する設計。

実装メモ

• 型推論（pyright/mypy）で戻り値型が正しく推論されるよう、@overload を使用している
• 外部ライブラリ関数のラッピングでは functools.wraps が元関数に適用される

実装概要

Spot._execute_sync() と Spot._execute_async() が実行エンジンの中核。 両メソッドは同一のフロー（キー生成→キャッシュ検索→Herd待機→関数実行→保存）を それぞれ同期/非同期のセマンティクスで実装する。 mark() がデコレーション時に inspect.iscoroutinefunction() で判定し、 適切な方を選択する。

設計判断

同期・非同期の並行実装

_execute_sync と _execute_async は処理フローが同一だが、 await の有無やロック機構（threading.Event vs asyncio.Future）が異なるため、 共通化せず並行して実装している。DRY 原則よりも明瞭性・デバッグ容易性を優先した。

Herd 結果の保存前共有

Herd protection の結果ボックスへの結果格納は、DB/Blob 保存の前に行う。 これにより、保存が失敗しても待機中のスレッド/タスクは結果を受け取れる。 「保存の失敗で実行結果が失われる」ことを防ぐ意図的な設計。

バックグラウンド保存のエラー隔離

save_sync=False 時の保存エラーは on_background_error コールバックに 通知し、ERROR ログを出力するが、例外を再送出しない。 関数の実行自体は成功しているため、ユーザーに例外を見せるのは不適切と判断した。

実装メモ

• フック呼び出し（pre_execute, on_cache_hit, on_cache_miss）は try/except で囲み、フック内の例外が実行結果に影響しないようにしている
• 自動エビクションは _eviction_guard_lock で非ブロッキングにガードし、 並行エビクションの重複実行を防止している
• _execute_async 内の保存処理は _BackgroundLoop.submit() でコルーチンとして投入される

実装概要

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 戦略の引数はキー計算から完全に除外される（値に関係なくキャッシュヒット）

実装概要

SQLiteTaskDB クラスが中核。Writer Thread + Reader Threads パターンで実装。 単一の _writer_thread（デーモン）が _write_queue から書き込みタスクを取り出して直列処理し、読み取りは threading.local() のスレッドローカル接続で並行実行する。 WAL モードにより読み取りと書き込みの並行性を確保している。

スキーマ初期化（RAII）

__init__ の末尾で init_schema() を呼び出し、構築後のインスタンスは即座に使用可能な状態とする。 呼び出し元（core.Spot やファクトリ）が明示的に init_schema() を呼ぶ必要はない。 init_schema() は冪等であり、複数回呼び出しても安全である。

タイムアウトの実装

• _enqueue_write 内で task.event.wait(timeout=0.5) をループさせ、self.timeout を超えた場合にフェイルファスト処理を行う。
• PENDING: task.try_cancel() でキュー内キャンセル。
• RUNNING: self._writer_conn.interrupt() を呼び出して実行中の SQLite クエリを強制終了させ、呼び出し元に TimeoutError を返す。
• interrupt 後、ライタースレッド側の例外処理を待つための猶予時間を設け、可用性と整合性を両立させている。

設計判断

SQLite特有のデータベースロック（Database Is Locked）を回避するため。単一のWriter Threadで書き込みを直列化し、WALモードとスレッドローカルなReaderを組み合わせることで、高い並行読み取り性能と安全な書き込みを両立する実装とした。

実装概要

DB 層のプロトコル階層を定義。TaskDBCore（ランタイム必須の CRUD）、 Flushable（書き込み同期）、Shutdownable（安全な停止）、 Maintenable（GC・統計等の管理操作）の4つのプロトコルと、 それらを統合した TaskDBMaintenable を提供する。 TaskDBBase は ABC として Maintenable のデフォルト実装（安全な no-op）を提供する。

設計判断

プロトコルの細分化

単一の巨大インターフェースではなく、責務ごとにプロトコルを分割した。 これにより、カスタム DB 実装は TaskDBCore のみ実装すればランタイムで動作し、 メンテナンス機能は段階的にオプトインできる。

デフォルト実装の安全性

TaskDBBase のメンテナンスメソッド（delete_expired(), prune() 等）は デフォルトで空リスト返却や no-op を行い、サブクラスが未実装でも安全に動作する。 CLI の gc コマンドが未対応の DB バックエンドでもエラーにならない設計。

実装メモ

• Flushable.flush(timeout) のデフォルトは no-op。SQLiteTaskDB のみがキュー同期を実装
• Shutdownable.shutdown(wait) のデフォルトは no-op。リソースを持たない軽量実装に配慮
• カスタム DB 実装は isinstance(db, Maintenable) で機能の有無を判定できる

実装概要

• LocalStorage クラスが BlobStorageBase を実装。 ファイルは {base_dir}/{key}.bin 形式で保存される。

• save() は tempfile.mkstemp() → fsync() → os.replace() の アトミック書き込みパターンで実装。

設計判断

アトミック書き込みパターン

一時ファイルに書き込み → fsync でディスクに確実に反映 → os.replace で アトミックにリネーム。この3段階により、書き込み中のクラッシュや 並行アクセスでファイルが半壊状態になることを防ぐ。 一時ファイルには .spot_tmp 接尾辞を使用し、残存時のクリーンアップを容易にした。

パストラバーサル防止の二重ガード

• save() / _validate_key(): キーに .., /, \ を含む場合に ValidationError

• load() / delete(): 解決済みパスが base_dir.is_relative_to() を満たすか検証 二重のチェックにより、キー経由とロケーション経由の両方のパストラバーサルを防ぐ。

実装メモ

• 初期化時に base_dir を絶対パスに正規化し、ディレクトリと .gitignore を自動作成

• delete() は冪等。ファイル不在時もエラーを送出しない。パーミッションエラーは警告のみ

• list_keys() は rglob("*.bin") でレガシーサブディレクトリ構造にも対応

• clean_temp_files() は猶予期間（デフォルト24時間）超過の .spot_tmp ファイルのみ削除。 ファイルロック（アンチウイルス等）のエラーは安全に無視する

• prune_empty_dirs() はボトムアップで走査し、.DS_Store 等のシステムファイルのみの ディレクトリも空とみなして削除する。base_dir 自体は保持する

実装概要

S3Storage クラスが BlobStorageBase を実装。 s3://bucket/prefix/ 形式の URI を解析し、boto3 の S3 クライアントを使用。 ファイルは {prefix}/{key}.bin のキーで S3 に保存される。

設計判断

オプショナル依存のガード

boto3 は import 時にガードし、未インストール時は クラス定義は成功するがインスタンス化で明確なエラーメッセージを表示する。 beautyspot 全体が boto3 に依存しないよう、遅延インポートパターンを採用。

URI ベースのバックエンド選択

s3://bucket/prefix 形式の URI から bucket と prefix を自動解析する _parse_s3_uri() ヘルパーにより、ファクトリ関数がスキームに基づいて LocalStorage と S3Storage を透過的に切り替えられる。

実装メモ

• save() は upload_fileobj() を使用し、5GB 超のデータにも マルチパートアップロードで対応する
• ロケーションは完全な S3 URI（s3://bucket/prefix/key.bin）を返す
• list_keys() は paginator で全キーを列挙し、prefix を除いた相対キーを返す
• get_mtime() は head_object で LastModified を取得（GC の grace period 判定用）

実装概要

StoragePolicyProtocol が should_save_as_blob(data: bytes) -> bool を定義。 3つの実装を提供: - ThresholdStoragePolicy: len(data) > threshold で判定 - WarningOnlyPolicy: 常に False を返し、閾値超過時に WARNING ログを出力 - AlwaysBlobPolicy: 常に True を返す

設計判断

Strategy パターンによるポリシー分離

保存先判定ロジックを core.Spot から分離し、差し替え可能なポリシーオブジェクトに 委譲する。@mark(save_blob=True/False) の明示指定はポリシーより優先されるが、 save_blob=None（デフォルト）時にポリシーが判定を行う。

WarningOnlyPolicy をデフォルトにした理由

v2.0 との後方互換性を維持するため。v2.0 では全データが DB 直接保存だったため、 デフォルトを ThresholdStoragePolicy にすると既存ユーザーの挙動が変わる。 WARNING ログにより、ユーザーに Blob 分離の恩恵を段階的に周知する。

実装メモ

• 各ポリシーは dataclass で実装し、threshold パラメータを属性として保持
• WarningOnlyPolicy のログは warnings.warn ではなく logging.warning を使用。 ユーザーコードの警告フィルタに影響されないため

実装概要

MsgpackSerializer クラスが SerializerProtocol と TypeRegistryProtocol を実装。 dumps(obj) -> bytes / loads(data) -> Any が主要 API。 カスタム型は msgpack の ExtType(code, payload) で拡張する。 _default_packer() がエンコード時のカスタム型ディスパッチ、 _ext_hook() がデコード時の型復元を行う。

設計判断

Copy-on-Write レジストリ

_encoders / _decoders 辞書は register() 時に新しい辞書を作成して アトミックに差し替える（CoW）。読み取り側はスナップショットを参照するため、 ロックなしで安全に読める。GIL に依存せず、PEP 703（free-threading）にも 対応できる設計。世代カウンタ _registry_generation をレジストリ差し替えの前に インクリメントすることで、読み取り側が古いキャッシュを使い続けることを防ぐ。

スレッドローカル LRU キャッシュ

MRO スキャンの結果（サブクラス→登録済み親クラスの解決）を threading.local() の OrderedDict にキャッシュする。_cache_generation と _registry_generation を比較し、 世代が変わったらキャッシュを破棄する。LRU のサイズ上限は max_cache_size で制御。

MRO スキャンによるサブクラス自動解決

Pydantic モデルのサブクラスのように、親クラスが登録済みなら サブクラスも自動的に同じエンコーダで処理できる。type(obj).__mro__ を走査し、 最初にマッチした登録型のエンコーダを使用する。

実装メモ

• register() の code は 0-127（msgpack ExtType の制約）
• 同一型や同一 code の重複登録は ConfigurationError で拒否
• _ext_hook 内のデシリアライズは再帰的に msgpack.unpackb(ext_hook=self._ext_hook) を 呼ぶことで、ネストされたカスタム型も復元できる
• SerializationError のメッセージには未登録型のヒント（spot.register() の使い方）を含める

実装概要

2つのレイヤーで構成: - MsgpackSerializer.register(type, code, encoder, decoder): 低レベルの型登録 API - Spot.register() / Spot.register_type(): ユーザー向けの高レベル API

Spot.register() はデコレータ形式、Spot.register_type() は命令形式で、 いずれも内部で serializer.register() に委譲する（TypeRegistryProtocol 準拠時のみ）。

設計判断

二層 API の提供

デコレータ形式 @spot.register(code=1, ...) はクラス定義と同時に登録でき、 宣言的で読みやすい。命令形式 spot.register_type(MyClass, code=1, ...) は 外部ライブラリのクラスなどデコレートできない場合に使用する。

TypeRegistryProtocol による条件分岐

シリアライザが TypeRegistryProtocol を実装していない場合（カスタムシリアライザ）、 register() / register_type() は ConfigurationError を送出する。 これにより、型登録非対応のシリアライザを使用する場合のエラーメッセージが明確になる。

実装メモ

• register() の内部で _write_lock を取得してから CoW で辞書を差し替える
• Pydantic モデルの factory デコーダは model_validate(data) を使用し、 バリデーション付きの復元が可能
• code の重複登録はエラーとなるが、同一型の再登録（code 変更）もエラーとなる

実装概要

_BackgroundLoop クラスが非同期タスクのバックグラウンド実行を管理する。 初期化時に asyncio.new_event_loop() で新しいイベントループを作成し、 _thread（デーモンスレッド）上で loop.run_forever() を実行する。 外部からは submit() を通じてコルーチンを投入でき、run_coroutine_threadsafe で スレッドセーフにループへ渡される。

設計判断

デーモンスレッドと明示的なシャットダウン

スレッドは daemon=True とし、メインスレッド終了時にプロセスがブロックされないようにしている。 しかし、安全なリソース解放のために drain() メソッドを提供し、 投入された全タスクの完了を drain_timeout の範囲で待機する。

独立したイベントループ

メインスレッドのイベントループと競合しないよう、専用のイベントループを 作成してバックグラウンドスレッドで駆動する。これにより save_sync=False 時の 保存処理などが、呼び出し元の asyncio 環境から完全に隔離される。

実装メモ

• submit() は投入されたタスクを _tasks 集合に登録し、add_done_callback で 完了時に自身を削除することで、未完了タスクの追跡を可能にしている
• シャットダウン時の競合を防ぐため、_lock による排他制御を行っている
• atexit ハンドラとしてもシャットダウンが登録される

実装概要

Spot クラスにおいて、バックグラウンド書き込みの同期と完了待機を制御する。 save_sync=False の場合、キャッシュへの保存処理は _bg_loop.submit() で バックグラウンドに投入される。これら未完了のタスクやDBキューを同期するため、 flush() およびコンテキストマネージャによる drain が実装されている。

設計判断

flush と drain の使い分け

• flush(): DBライタースレッドのキュー (self.db.flush()) を空になるまで待機する
• __exit__: コンテキストマネージャ終了時に flush() を呼び出した上で、 さらに _bg_loop.drain() を呼び出し、非同期タスクの完了も待つ これにより、スクリプト終了時やバッチ処理の区切りで、データの完全な永続化を保証する。

バックグラウンドエラーの隔離

バックグラウンド保存時のエラーは呼び出し元のメインフローを妨げないよう、 on_background_error コールバックに通知され、ログ出力のみ行う。 例外の再送出は行わない。

実装メモ

• flush() にはタイムアウトを設定でき、ハングアップを防止している
• on_background_error は SaveErrorContext を引数に取り、失敗時の キーや関数の詳細情報を提供する

実装概要

LifecyclePolicy クラスは Rule オブジェクトのリストを保持し、 関数名に基づいてキャッシュの保持期間を決定する。 resolve() メソッドが fnmatch.fnmatch() を使って関数名をパターンと照合し、 最初にマッチしたルールの保持期間を返す。

設計判断

First-Match セマンティクス

ルールのリストは順序が意味を持ち、最初にマッチしたものが採用される。 これにより、特定プレフィックスの関数には短い保持期間を設定し、 最後に *（ワイルドカード）でデフォルトポリシーを設定するような フォールバック構造が簡単に記述できる。

resolve_with_fallback の導入

後方互換性と柔軟性のため、まず func_identifier (モジュール名付きの完全修飾名) で マッチングを試み、マッチしなかった場合は func_name (短い関数名) で再度マッチングを 試みる resolve_with_fallback() を提供している。

default_retention の導入

LifecyclePolicy コンストラクタに default_retention パラメータを追加。 どのルールにもマッチしない場合に返す保持期間を指定できる。 LifecyclePolicy.default() は default_retention="30d" で生成し、 デフォルトで30日の保持期間を設定する。

実装メモ

• LifecyclePolicy.default() は空のルールリスト + default_retention="30d" を持つ
• default_retention=None を指定すれば従来通り無期限保持となる

実装概要

Retention クラスを名前空間として使用し、保持期間のパースや 特殊な定数（INDEFINITE, FOREVER）を管理する。 parse_retention() 関数は文字列（"7d", "12h"等）、timedelta、 または秒数（int/float）を受け取り、標準化された timedelta オブジェクトに変換する。

設計判断

_ForeverSentinel シングルトン

Retention.FOREVER はポリシーを強制的にバイパスするための特殊値。 PEP 703 (free-threading) 環境での安全性を考慮し、 _ForeverSentinel は threading.Lock を用いたダブルチェックロッキングで 厳密なシングルトンとして実装されている。

直感的な文字列表現のサポート

"7d", "12h", "30m", "10s" のような文字列フォーマットを 正規表現 _TIME_PATTERN でパースすることで、設定ファイルや ハードコード時の可読性を高めている。

実装メモ

• parse_retention() は無効なフォーマットや負の値に対して ValidationError を送出する
• _ForeverSentinel は __bool__() で True を返すようオーバーライドされている

実装概要

LimiterProtocol を実装する TokenBucket クラス。 GCRA (Generic Cell Rate Algorithm) に基づき、スレッドセーフおよび 非同期対応のスムーズなレートリミッタを提供する。 内部状態として Theoretical Arrival Time (TAT) を保持し、 consume() で同期的スリープ、consume_async() で非同期的スリープを行う。

設計判断

GCRAアルゴリズムの採用

伝統的なトークンバケットとは異なり、長時間アイドル後に 一気にバーストを許容しない「Strict Pacing」を実現できる。 TATの更新と現在時刻の比較だけで待機時間を計算できるため、 メモリ効率と計算効率に優れる。

モノトニッククロックの利用

時刻の取得に time.monotonic() を使用し、システム時刻の変更（NTP同期など）の 影響を受けない堅牢な設計としている。

実装メモ

• _consume_reservation() メソッドが待機時間の計算と TAT 更新を threading.Lock でアトミックに行う
• cost > max_cost（バケット容量超過）の場合は、どれだけ待っても 処理できないため即座に ValueError を送出する
• 同期パスは time.sleep()、非同期パスは asyncio.sleep() で待機する

実装概要

タスク実行ライフサイクルに介入するインターフェース HookBase と、 そのスレッドセーフ版 ThreadSafeHookBase の実装。 pre_execute, on_cache_hit, on_cache_miss の各コールバックが提供される。 ThreadSafeHookBase は __init_subclass__ を利用し、サブクラスで定義された フックメソッドを自動的にロックでラップする。

設計判断

init_subclass による透過的ロッキング

ユーザーが手動でロックを書く手間を省くため、メタクラス的なアプローチを採用。 クラス定義時にフックメソッドを抽出し、_wrap_with_lock デコレータで包むことで、 ユーザーコードを汚さずに完全な排他制御を実現している。

RLock（再入可能ロック）の使用

当初の Lock から RLock に変更された。 サブクラスが super().pre_execute(...) のように親のメソッドを呼び出した際、 同一スレッドが再度ロックを取得しようとしてデッドロックする問題を防ぐため。

実装メモ

• _wrap_with_lock は functools.wraps を使い、元のメタデータを保持する
• ThreadSafeHookBase は __getattr__ をオーバーライドし、 super().__init__() の呼び出し忘れに対して親切なエラーメッセージを返す

実装概要

MaintenanceService クラスがDBとBlobストレージ間の整合性チェック、 期限切れキャッシュの削除、孤立ファイルの検出といったガベージコレクション（GC）を担当。 主にCLIの beautyspot gc コマンドから呼び出される。 対象となる DB (TaskDBMaintenable) とストレージ (BlobStorageMaintenable) を受け取り、 複数のフェーズに分けてクリーンアップを実行する。

設計判断

5フェーズのクリーンアッププロセス

clean_garbage() は以下の順序で安全にGCを実行する： 1. 期限切れDBレコードの削除 2. Blobストレージの一時ファイル（.spot_tmp）のクリーンアップ 3. 孤立したBlobファイル（DBに存在しないファイル）の特定 4. 孤立ファイルの削除 5. 空ディレクトリの剪定

Grace Period (猶予期間) の導入

実行中のタスクがBlobを書き込んだ直後で、まだDBにメタデータが保存されていない タイミングでGCが走ると、必要なファイルが孤立と誤認されるリスクがある。 これを防ぐため、orphan_grace_seconds（デフォルト60秒）より新しいファイルは 孤立判定から除外する設計とした。

実装メモ

• 孤立ファイルの検出 scan_garbage() は、ストレージの全キーを列挙し、 DBの get_blob_keys() との差分を取ることで行う
• 複数プロジェクトを一括でGCするためのヘルパー scan_orphan_projects() も提供される

実装概要

Typer を利用したコマンドラインインターフェースの実装。 list, show, stats, clear, clean, gc, prune, version 等の コマンドを提供し、rich ライブラリを用いてコンソール出力（テーブル、パネル、 プログレスバー等）をリッチにフォーマットしている。

設計判断

Typer と Rich の組み合わせ

Typer は型ヒントベースでコマンドやオプションを定義でき、コードの記述量と メンテナンスコストを大幅に削減できる。Rich による出力は、単なるテキストではなく 構造化された情報（JSONやMarkdown）の視認性を劇的に向上させ、DXを高める。

安全性を考慮した対話的プロンプト

clear や clean など、データを大規模に削除するコマンドについては、 --force オプションが指定されない限り、rich.prompt.Confirm を用いて ユーザーに明示的な確認を求めることで、誤操作によるデータ喪失を防いでいる。

実装メモ

• コマンドは MaintenanceService などの内部 API を利用して処理を行う
• 各コマンドは特定のプロジェクト (--project / -p) に対して操作を行うが、 一部のコマンド（list 等）はワークスペース全体の走査もサポートする

実装概要

beautyspot パッケージのメインエントリポイントとなる Spot ファクトリ関数の実装。 引数として渡された各コンポーネント（DB、Serializer、Storage等）を依存性注入（DI）で 解決し、デフォルトのコンポーネント（SQLiteTaskDB, MsgpackSerializer, LocalStorage等）を インスタンス化して CacheManager と _Spot コアエンジンを組み立てる。

設計判断

Factory 関数による Composition

_Spot クラス自体のコンストラクタは複雑な依存関係を要求するが、 ユーザー向けに Spot() 関数を提供することで、通常は name を渡すだけで 「ゼロ設定」で動作するようにカプセル化している。 同時に、高度なユーザーは各コンポーネントを自由に差し替え可能な DI アーキテクチャを維持している。

DB ライフサイクルの委譲

Spot() 関数内でデフォルトのDB（SQLiteTaskDB）を自動生成した場合、 spot._owns_db = True フラグを立て、Spotエンジンのシャットダウン時に DBも自動でクローズされるようにする。一方、ユーザーが明示的に db= を 渡した場合は、DBのライフサイクル管理は呼び出し元に委ねる（勝手に閉じない）。

実装メモ

• Storage Policy は save_blob フラグや引数によって WarningOnlyPolicy, AlwaysBlobPolicy 等に解決される
• __all__ に各種プロトコルやデフォルト実装、例外クラスをエクスポートし、 ライブラリとしての公開API境界を明確に定義している

実装概要

CacheManager クラス内で、Thundering Herd（キャッシュミス時に同一キーへの 大量アクセスが同時に発生する問題）を防止する直列化機構を実装。 _inflight 辞書で実行中のキーを管理し、最初の1スレッド/タスクだけが関数を実行し、 後続の呼び出しは herd_sync / herd_async コンテキスト内でその完了を待機する。

設計判断

コンテキストマネージャによる例外安全性

実行者 (Executor) が処理中に例外（KeyboardInterrupt や asyncio.CancelledError を含む）で 中断された場合でも、_inflight 状態が残留して後続タスクを永続的にブロックすることを防ぐため、 herd_sync / herd_async をコンテキストマネージャとして提供する。 クリーンアップ処理（notify_and_cleanup_inflight）は finally ブロック内で 自動的に実行される。

同期・非同期の統合的保護

_inflight 辞書の値として (threading.Event, list[asyncio.Future], list[result]) の タプルを保持し、スレッドベースの待機 (Event.wait) と asyncio ベースの待機 (Future) の 両方を単一の管理下で混在できるようにしている。

タイムアウトと再試行（自己回復）

関数の実行がハングアップした場合に待機側が永遠にブロックされるのを防ぐため、 HERD_TIMEOUT（300秒）と HERD_MAX_RETRIES（3回）を設定。 タイムアウト時には警告ログを出しつつ再試行し、上限を超えれば TimeoutError で フェイルファストする堅牢な設計とした。

実装メモ

• notify_and_cleanup_inflight() で待機タスクへの結果伝播と _inflight からの削除を _inflight_lock によりアトミックに行う
• result_box（要素数1のリスト）をリファレンス渡しで共有することで、 Event が set された際に安全に結果を取得できるようにしている
• _notify_future() は call_soon_threadsafe を使い、非同期Futureに対して 別スレッドから安全に結果（または例外）をセットする

実装概要

storage.py 内の BlobStorageBase ABC が SPEC024 の中核実装。 5つの抽象メソッド（save, load, delete, list_keys, get_mtime）を定義し、 LocalStorage と S3Storage が具象実装として継承する。

加えて、ランタイム型チェックのために BlobStorageCore・Maintenable・ BlobStorageMaintenable の3つの Protocol クラスを定義し、 isinstance() での型判定を可能にしている（@runtime_checkable）。

設計判断

ABC と Protocol の併用

BlobStorageBase は ABC として抽象メソッドを強制する一方、 BlobStorageCore / Maintenable は Protocol として構造的部分型を提供する。 これにより、BlobStorageBase を継承しないサードパーティ実装でも isinstance(obj, BlobStorageCore) で利用可能になる柔軟性を確保した。

3層の Protocol 分割

• BlobStorageCore: 実行時に必要な最小限（save/load/delete）
• Maintenable: メンテナンス（GC）に必要な拡張（list_keys/get_mtime）
• BlobStorageMaintenable: 両方を兼備する完全版

これにより、save/load/delete のみを実装した軽量バックエンドも受け入れ可能。

ReadableBuffer 型エイリアス

bytes | bytearray | memoryview を ReadableBuffer として定義。 memoryview を受け入れることでゼロコピー書き込みが可能になり、 大きなデータを保存する際のメモリ効率を改善している。

実装メモ

• BlobStorageBase 自体はロジックを持たず、インターフェース定義のみ
• 各 @abstractmethod にはdocstringで契約を明記（冪等性、エラー時の挙動など）
• delete は冪等であるべきことを docstring で規定
• list_keys は delete と同じフォーマットの識別子を yield すべきことを規定

インスタンスの所有権と弱参照によるエグゼキュータのライフサイクル管理

コンテキストと課題

src/beautyspot/core.py において、非同期タスクのIOオフロード用に ThreadPoolExecutor がグローバル変数 _io_executor として定義されている。

この実装には以下の課題がある：

1. リソース制御の欠如: スレッド数（max_workers=4）がハードコードされており、ユーザーが実行環境（AWS Lambda、強力なサーバー等）に合わせて調整できない。
2. ゾンビプロセス: プロセス終了時に明示的なシャットダウンが行われないため、環境によってはゾンビプロセス化するリスクがある。
3. テスト困難性: グローバル変数はモック化が難しく、ユニットテストの分離を妨げる。

代替案として with 文（Context Manager）による管理も検討されたが、beautyspot の「デコレータを付与するだけで動作する」という簡易な利用体験（DX）を損なうため、採用には至らなかった。ユーザーコードを変更させずに、安全にリソースをクリーンアップする仕組みが必要である。

判断基準

• Developer Experience (DX): ユーザーに shutdown() の呼び出しや with 文を強制したくない。
• Configurability: スレッド数や Executor の実装をユーザーが制御できるようにしたい。
• Safety: プロセス終了時やインスタンス破棄時に、確実にスレッドプールを閉じたい。
• Memory Safety: クリーンアップ処理の登録によって、メモリリーク（循環参照）を引き起こしてはならない。

検討した選択肢

• Option 1: 現状維持（グローバル変数のまま）。
• Option 2: Project を Context Manager 化し、__exit__ で shutdown() を呼ぶ。
• Option 3: atexit モジュールを使い、終了時に shutdown() を呼ぶ。
• Option 4: インスタンス管理に変更し、weakref.finalize で自動クリーンアップを行う。

決定事項

採用した選択肢: Option 4.

Project クラスの設計を以下のように変更する：

1. Executorのインスタンス化: グローバル変数を廃止し、Project インスタンスごとに ThreadPoolExecutor を保持する。
2. Dependency Injection (DI): コンストラクタで外部 Executor の注入を許可する。
3. 所有権と責任の分離:
   • 外部注入 (executor 引数あり): Project はそれを借用するのみ。シャットダウンの責任はユーザー（呼び出し元）にあるため、自動クリーンアップは行わない。
   • 内部生成 (executor 引数なし): Project がライフサイクルを管理する責任を持つ。
4. 自動クリーンアップ: 内部生成した場合に限り、weakref.finalize を使用してシャットダウンを自動化する。

技術詳細: なぜ atexit ではなく weakref.finalize なのか？

単純な atexit.register(self.shutdown) を採用しなかった理由は、メモリリーク（循環参照）のリスク である。

• 問題点: atexit レジストリにインスタンスメソッド（self.shutdown）を登録すると、atexit が self への強参照（Strong Reference）を保持し続ける。これにより、アプリケーション実行中に Project インスタンスが不要になってもガベージコレクション（GC）されず、メモリリークを引き起こす。これを防ぐには atexit.unregister が必要になるが、管理が複雑になる。
• 解決策: weakref.finalize(self, func, *args) を採用する。
  • self がGCされた時点で、即座に func（クリーンアップ処理）が実行される。
  • プログラム終了時まで self が生存していた場合も、atexit 相当のタイミングで func が実行される。
  • 重要: クリーンアップ関数 _shutdown_executor は staticmethod とし、引数には self ではなく self.executor のみを渡す。これにより、ファイナライザが self を参照し続けて寿命を延ばしてしまう事故を防ぐ。

# Implementation Sketch
class Project:
    def __init__(self, ...):
        # ...
        self.executor = ThreadPoolExecutor(...)
        # self を参照しないよう、executor オブジェクトだけを渡す
        self._finalizer = weakref.finalize(self, self._shutdown_executor, self.executor)

    @staticmethod
    def _shutdown_executor(executor):
        executor.shutdown(wait=True)

影響・結果

• ポジティブ:
  • ユーザーはリソース管理を意識する必要がなくなり、APIもシンプルに保たれる。
  • Project インスタンスがGCされたタイミングでスレッドプールも回収されるため、リソース効率が良い。
  • DIにより、テスト時にモックExecutorを差し込むことが容易になる。
• ネガティブ:
  • core.py の実装において、GCの挙動と weakref の仕様を理解したコーディングが必要になり、内部的な複雑性が若干増す。
  • Project インスタンスを大量に生成・破棄するような特殊な使い方をした場合、スレッドプールの生成コストがオーバーヘッドになる可能性がある（ドキュメントでシングルトン的な利用を推奨することで緩和する）。

関数引数のための安定したハッシュ化

コンテキストと課題

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

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

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

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

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

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

判断基準

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

検討した選択肢

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

決定事項

採用した選択肢: Option 3.

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

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

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

影響・結果

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

スムーズなレートリミッター（GCRA）

コンテキストと課題

beautyspot のレート制限機能 (limiter) において、以下の課題があった。

1. Idle Burst: トークンバケット方式では、アイドル中にトークンが溜まり、再開直後にバースト（集中アクセス）が発生してしまう。これを防ぐために容量(capacity)を小さくすると、今度は巨大なコストを持つタスクが実行できなくなる（デッドロック）問題が発生する。
2. Start Dash Prevention: プロセス起動直後に複数のタスクが同時に走るのを防ぎたいが、最初の1回目まで待たされるのは避けたい。
3. Clock Dependency: システム時刻の変更に堅牢である必要がある。
4. Max Cost Guard: tokens_per_minute を単発タスクのコスト上限とする。
   • これを超えるコストが consume() に渡された場合、即座に ValueError を送出する。
   • 理由: APIの物理的なレート制限を超えるリクエストは、待機したところで成功する見込みが薄く、早期に設定ミスや入力ミスをユーザーに通知すべきであるため。

判断基準

• Burst Prevention: 長時間のアイドル後に大量のタスクが集中するのを防ぎ、一定のレートを維持すること。
• Deadlock Freedom: レート制限設定値（TPM）以下のコストであれば、どんなに大きなコストのタスクでも（待機時間を経て）実行可能であること。
• Zero Initial Latency: 最初のタスクは待機時間なしで即座に開始できること。
• Fail Fast: システムの設定（TPM）で物理的に不可能なリクエストは、実行前に即座にエラーにすること。

検討した選択肢

• Option 1: トークンバケット（既存実装）。バーストしやすく、容量設定によってはデッドロックのリスクがある。
• Option 2: GCRA (Generic Cell Rate Algorithm)。別名 "Leaky Bucket as a Meter"。定速性が高く、貯金を許さないためバーストに強い。

決定事項

採用した選択肢: Option 2.

アルゴリズムをトークンバケットから GCRA (Generic Cell Rate Algorithm) に変更する。

• 理論的到達時刻 (TAT: Theoretical Arrival Time) を管理する。
• タスクが来ると、そのコスト分だけ TAT を未来へ進める。
• 現在時刻 < TAT ならば、その差分だけ待機（sleep）してから実行する。
• 現在時刻 >= TAT （アイドル状態）ならば、TAT を現在時刻にリセットしてから計算する（過去の貯金は捨てる）。

影響・結果

• ポジティブ:
  • 完全な定速運転: アイドル後でもバーストせず、設定されたレート（TPM）を厳守する。
  • デッドロックフリー: どんなに大きなコストのタスクでも、必要な待機時間を計算して処理できる。
  • 即時起動: 最初の1回のリクエストは待ち時間なしで実行され、2回目以降からペーシングが効く。
  • Fail Fast: 設定値を超える無茶なリクエストを早期発見できる。
• ネガティブ:
  • 実装が「トークンを消費する」という直感的なメタファーから少し離れる（コード内の説明で補足する）。

耐障害性のあるデシリアライズと明示的なバージョニング

コンテキストと課題

Pythonの pickle は、保存されたオブジェクトのクラス定義と現在のコードが一致していることを前提とします。 開発中はクラス定義が頻繁に変更されるため、過去のキャッシュを読み込む際に AttributeError 等が発生し、アプリケーションがクラッシュする問題がありました。

判断基準

• Fault Tolerance: キャッシュデータがコードの変更と不整合を起こしても、アプリケーションをクラッシュさせないこと。
• Developer Experience (DX): 開発中の頻繁なリファクタリングを妨げないこと。
• Explicit Control: ユーザーが意図したタイミングでキャッシュを無効化できる手段を提供すること。
• Safe Deployment: 本番環境において、安全にキャッシュを刷新できること。

検討した選択肢

• Option 1: デシリアライズエラー時に例外を送出し、実行を停止する（既存挙動）。
• Option 2: エラーを捕捉して「キャッシュミス」として扱い、再計算を行う。あわせて明示的な version 指定による無効化を可能にする。

決定事項

採用した選択肢: Option 2.

1. Fail Safe (Auto Recalc): Storage.load() でデシリアライズエラー（クラス不整合や破損）が発生した場合、これを CacheCorruptedError として捕捉し、core.py 側で 「キャッシュミス」 として扱う。これによりアプリをクラッシュさせず、自動的に再計算を行う。
2. Explicit Versioning: ユーザーが意図的にキャッシュを無効化できるよう、@task デコレータに version 引数を追加する。これを変更するとキャッシュキーが変わり、古い（互換性のない）キャッシュを参照しなくなる。
3. User Guidance: 自動再計算が発生した際、ログに「コード変更時は version の更新を検討してね」というヒントを出力し、ベストプラクティスへ誘導する。

影響・結果

• ポジティブ:
  • 開発中のクラッシュを防ぎ、スムーズなDXを提供する。
  • 本番運用時でも、version を使うことで安全なデプロイ（キャッシュ切り替え）が可能になる。
• ネガティブ:
  • 再計算コストが発生する（が、クラッシュよりはマシである）。

インスタンスの所有権と弱参照によるエグゼキュータのライフサイクル管理

コンテキストと課題

src/beautyspot/core.py において、非同期タスクのIOオフロード用に ThreadPoolExecutor がグローバル変数 _io_executor として定義されている。

この実装には以下の課題がある：

1. リソース制御の欠如: スレッド数（max_workers=4）がハードコードされており、ユーザーが実行環境（AWS Lambda、強力なサーバー等）に合わせて調整できない。
2. ゾンビプロセス: プロセス終了時に明示的なシャットダウンが行われないため、環境によってはゾンビプロセス化するリスクがある。
3. テスト困難性: グローバル変数はモック化が難しく、ユニットテストの分離を妨げる。

代替案として with 文（Context Manager）による管理も検討されたが、beautyspot の「デコレータを付与するだけで動作する」という簡易な利用体験（DX）を損なうため、採用には至らなかった。ユーザーコードを変更させずに、安全にリソースをクリーンアップする仕組みが必要である。

判断基準

• Developer Experience (DX): ユーザーに shutdown() の呼び出しや with 文を強制したくない。
• Configurability: スレッド数や Executor の実装をユーザーが制御できるようにしたい。
• Safety: プロセス終了時やインスタンス破棄時に、確実にスレッドプールを閉じたい。
• Memory Safety: クリーンアップ処理の登録によって、メモリリーク（循環参照）を引き起こしてはならない。

検討した選択肢

• Option 1: 現状維持（グローバル変数のまま）。
• Option 2: Project を Context Manager 化し、__exit__ で shutdown() を呼ぶ。
• Option 3: atexit モジュールを使い、終了時に shutdown() を呼ぶ。
• Option 4: インスタンス管理に変更し、weakref.finalize で自動クリーンアップを行う。

決定事項

採用した選択肢: Option 4.

Project クラスの設計を以下のように変更する：

1. Executorのインスタンス化: グローバル変数を廃止し、Project インスタンスごとに ThreadPoolExecutor を保持する。
2. Dependency Injection (DI): コンストラクタで外部 Executor の注入を許可する。
3. 所有権と責任の分離:
   • 外部注入 (executor 引数あり): Project はそれを借用するのみ。シャットダウンの責任はユーザー（呼び出し元）にあるため、自動クリーンアップは行わない。
   • 内部生成 (executor 引数なし): Project がライフサイクルを管理する責任を持つ。
4. 自動クリーンアップ: 内部生成した場合に限り、weakref.finalize を使用してシャットダウンを自動化する。

技術詳細: なぜ atexit ではなく weakref.finalize なのか？

単純な atexit.register(self.shutdown) を採用しなかった理由は、メモリリーク（循環参照）のリスク である。

• 問題点: atexit レジストリにインスタンスメソッド（self.shutdown）を登録すると、atexit が self への強参照（Strong Reference）を保持し続ける。これにより、アプリケーション実行中に Project インスタンスが不要になってもガベージコレクション（GC）されず、メモリリークを引き起こす。これを防ぐには atexit.unregister が必要になるが、管理が複雑になる。
• 解決策: weakref.finalize(self, func, *args) を採用する。
  • self がGCされた時点で、即座に func（クリーンアップ処理）が実行される。
  • プログラム終了時まで self が生存していた場合も、atexit 相当のタイミングで func が実行される。
  • 重要: クリーンアップ関数 _shutdown_executor は staticmethod とし、引数には self ではなく self.executor のみを渡す。これにより、ファイナライザが self を参照し続けて寿命を延ばしてしまう事故を防ぐ。

# Implementation Sketch
class Project:
    def __init__(self, ...):
        # ...
        self.executor = ThreadPoolExecutor(...)
        # self を参照しないよう、executor オブジェクトだけを渡す
        self._finalizer = weakref.finalize(self, self._shutdown_executor, self.executor)

    @staticmethod
    def _shutdown_executor(executor):
        executor.shutdown(wait=True)

影響・結果

• ポジティブ:
  • ユーザーはリソース管理を意識する必要がなくなり、APIもシンプルに保たれる。
  • Project インスタンスがGCされたタイミングでスレッドプールも回収されるため、リソース効率が良い。
  • DIにより、テスト時にモックExecutorを差し込むことが容易になる。
• ネガティブ:
  • core.py の実装において、GCの挙動と weakref の仕様を理解したコーディングが必要になり、内部的な複雑性が若干増す。
  • Project インスタンスを大量に生成・破棄するような特殊な使い方をした場合、スレッドプールの生成コストがオーバーヘッドになる可能性がある（ドキュメントでシングルトン的な利用を推奨することで緩和する）。

ダッシュボードのインタラクションモデル

コンテキストと課題

現状のダッシュボード (dashboard.py) では、タスク一覧の表示と詳細データの復元操作が分離しています。 ユーザーは一覧テーブルで対象を確認した後、別途ドロップダウンメニューから対応する cache_key (ハッシュ値) を手動で探し出す必要があり、認知負荷が高い状態です。 プロジェクトの依存関係として streamlit>=1.51.0 が確保されており、インタラクティブなデータフレーム機能が利用可能となっています。

判断基準

• Lower Cognitive Load: ユーザーがハッシュ値を意識することなく、直感的にデータを操作できること。
• Seamless Navigation: 一覧での選択が即座に詳細ビューに反映されること。
• Modern UI Experience: Streamlit の最新機能を活用し、洗練された操作感を提供すること。

検討した選択肢

• Option 1: 現状維持（テーブルと選択用ドロップダウンの分離）。
• Option 2: st.dataframe の on_select 機能を使用し、テーブル行のクリックによって詳細ビュー（Restore Data）のコンテキストを切り替える方式。

決定事項

採用した選択肢: Option 2.

st.dataframe の on_select 機能を使用し、テーブル行のクリックによって詳細ビューのコンテキストを切り替える方式を採用します。これにより、ユーザーはテーブル上のレコードを直接クリックするだけで、そのタスクの詳細や保存されたデータを復元できるようになります。

影響・結果

• ポジティブ:
  • ユーザーは直感的にレコードを選択・復元できる。
  • フィルタリングされた結果に対しても、正しい行インデックスで詳細へアクセスできる。
• ネガティブ:
  • Streamlit の古いバージョン（<1.35）との互換性が失われる（ただし pyproject.toml でバージョン指定済みのため許容）。

セマンティックなコンテンツタイプのサポート

コンテキストと課題

生成AIタスクの出力は、テキストだけでなく、画像、構造化データ、ダイアグラム（Mermaid, Graphviz/DOT, HTML）など多岐にわたります。 現状のデータベーススキーマ（result_type = FILE | DIRECT）は「データの保存形式」しか保持しておらず、「データの意味的種類（Semantic Type）」が不明であるため、ダッシュボードでの復元時に適切な可視化（レンダリング）ができません。

また、beautyspot はライブラリとしてユーザーの手元で動作するため、複雑なマイグレーション手順や重量級の依存関係（Alembicなど）を強制することはUXを損なうという課題があります。

判断基準

• Rich Visualization: 生成された図やデータを、ダッシュボード上で適切な形式で閲覧できること。
• Zero-Touch Upgrade: スキーマ変更時にユーザーが手動でマイグレーションコマンドを打つ必要がないこと。
• Lightweight: ライブラリの依存関係を最小限に保つこと。
• Type Safety: データの保存形式（Blob/Text）と意味（Mermaid/Image等）を明確に分離すること。

検討した選択肢

• Option 1: 保存されたデータの拡張子や中身から動的に型を推論する。
• Option 2: スキーマに content_type カラムを追加し、開発者が @task で明示的に指定できるようにする。あわせて自動マイグレーション機能を実装する。

決定事項

採用した選択肢: Option 2.

1. Database Schema & Migration

• Schema Change: tasks テーブルに content_type (TEXT) カラムを追加する。
• Migration Strategy: "Auto-Migration on Startup" を採用する。
  • Alembic等は導入しない（依存関係の軽量化とUX維持のため）。
  • Project 初期化時（_init_db）に PRAGMA table_info でカラムの存在を確認し、不足していれば標準ライブラリのみで ALTER TABLE を自動実行する。

2. Type Definition

• src/beautyspot/types.py を新設し、ContentType クラスで定数を管理する。
• Graphviz (DOT) と Mermaid を明確に区別する。
  • ContentType.GRAPHVIZ (text/vnd.graphviz)
  • ContentType.MERMAID (text/vnd.mermaid)

3. Interface

• @project.task デコレータに content_type 引数を追加し、開発者が戻り値の型を宣言できるようにする。

4. Rendering Strategy (Dashboard)

• Graphviz: Pythonの graphviz ライブラリと st.graphviz_chart を使用する。
• Mermaid: Streamlit標準コンポーネントがないため、st.components.v1.html を使用して Mermaid.js (CDN) を注入し、ブラウザ側でレンダリングする。

5. Dependencies

• pyproject.toml に graphviz>=0.20.1 を追加する。

影響・結果

• ポジティブ:
  • ダッシュボードで、生成AIが出力したアーキテクチャ図やフローチャートを直感的に閲覧できるようになる。
  • ユーザーはデータベースのアップグレード作業を意識する必要がない（自動化）。
  • データの「中身」を解析して表示形式を推測する不安定なロジックを排除できる。
• ネガティブ:
  • OS依存: Graphvizのレンダリングには、ユーザー環境に dot コマンド（OSレベルのパッケージ）がインストールされている必要がある。
  • Client-Side Rendering: MermaidはCDN経由のJS実行となるため、オフライン環境では表示されない場合がある。

Msgpackをデフォルトとしたカスタマイズ可能なシリアライズ戦略

コンテキストと課題

現在、beautyspot はキャッシュデータのシリアライズ（保存）に Python 標準の pickle を使用している。 これには以下の重大な課題がある：

1. セキュリティリスク (RCE): pickle は信頼できないデータを読み込む際に任意のコード実行（RCE）を引き起こす可能性があり、「共有キャッシュ」としての利用にリスクがある。
2. 互換性: Python のバージョンやライブラリのバージョンが変わると、クラス定義の不整合によりデシリアライズに失敗しやすい。
3. 代替案の欠点: 標準ライブラリの json は安全だが、画像などのバイナリデータを効率的に扱えず（Base64化でサイズ増）、タプルなどのPython固有型が失われる。

v1.0.0 リリースにあたり、「デフォルトで安全（Secure by Default）」 かつ 「拡張性（Extensibility）」 のあるシリアライズ戦略が必要である。

判断基準

• Security: デフォルト状態で RCE のリスクを排除したい。
• Performance: 画像やNumpy配列などのバイナリデータを、オーバーヘッドなく高速に扱いたい。
• Extensibility: ユーザーが独自のクラスや特殊な型（例: pandas.DataFrame）を、ライブラリ側の変更なしに保存・復元できるようにしたい。
• Developer Experience (DX): シリアライズ失敗時に、「どのオブジェクトが原因か」と「どうすれば解決できるか」を明確に示したい。

検討した選択肢

• Option 1: 現状維持（pickle のまま）。警告文で責任をユーザーに委ねる。
• Option 2: 標準ライブラリ json に一本化する。バイナリは Base64 エンコードを強制する。
• Option 3: msgpack を採用し、標準型のみサポートする。
• Option 4: msgpack を採用し、ExtType 機能を用いた「カスタム型登録システム」を実装する。

決定事項

採用した選択肢: Option 4.

シリアライザのバックエンドとして msgpack (MessagePack) を採用し、さらにユーザーが任意の型変換ロジックを注入できる TypeRegistry パターンを導入する。

1. 依存関係: msgpack>=1.0.0 を pyproject.toml に追加する。
2. デフォルトの挙動:
   • pickle はデフォルトから廃止（またはオプトイン化）する。
   • msgpack を使用し、安全な型のみをシリアライズする。
3. カスタム型の登録:
   • Project クラスに register_type(type, code, encoder, decoder) メソッドを追加する。
   • ユーザーは、シリアライズできない型（例: カスタムクラス）に対して、一意なID (code) と変換関数を登録することで対応できる。
4. エラーハンドリング:
   • 未登録の型に遭遇した場合、標準の TypeError ではなく、具体的なオブジェクト情報と register_type の利用を促す親切なエラーメッセージ (SerializationError) を送出する。

Technical Details / 技術詳細

msgpack の default (pack時) と ext_hook (unpack時) を活用し、拡張型を msgpack.ExtType としてラップする。

# Implementation Sketch

class Project:
    def __init__(self, ...):
        # ...
        self.serializer = MsgpackSerializer()

    def register_type(self, type_: type, code: int, encoder: Callable, decoder: Callable):
        """
        Register a custom serializer for a specific type.

        Args:
            type_: The class to handle (e.g. MyClass)
            code: Unique integer ID (0-127) for this type
            encoder: Function that converts obj -> bytes
            decoder: Function that converts bytes -> obj
        """
        self.serializer.register(type_, code, encoder, decoder)

# --- Internal ---

class MsgpackSerializer:
    def dump(self, obj):
        return msgpack.packb(obj, default=self._default_packer, use_bin_type=True)

    def load(self, data):
        return msgpack.unpackb(data, ext_hook=self._ext_hook, raw=False)

    def _default_packer(self, obj):
        # 登録済みの型なら ExtType に変換
        if type(obj) in self._encoders:
            code, encoder = self._encoders[type(obj)]
            return msgpack.ExtType(code, encoder(obj))

        # 未登録なら詳細なエラーを出す
        raise SerializationError(f"Object of type '{type(obj).__name__}' is not serializable...")

影響・結果

• Positive:
  • 安全性: pickle を排除することで、デフォルトでの脆弱性を解消できる。
  • パフォーマンス: json + Base64 よりも高速かつ省サイズでバイナリデータを扱える。
  • 柔軟性: ユーザーはライブラリをフォークすることなく、必要な型（Numpy, Pandas, Custom Class）の対応を追加できる。
• Negative:
  • 依存関係: 新たに msgpack パッケージへの依存が発生する（ただし軽量であるため許容範囲とする）。
  • 移行コスト: 既存の pickle で保存されたキャッシュデータ (.pkl) との互換性がなくなるため、v1.0.0 アップデート時にキャッシュクリア（DBリセット）が必要になる。

Updates (2025-12-11)

See ADR-0009 for further refinements regarding save_blob=False behavior (Msgpack + Base64) and size guardrails.

データベースの依存性の注入と抽象化

コンテキストと課題

これまでの beautyspot (v0.x) は、Project クラス内部で TaskDB (SQLite実装) をハードコードしてインスタンス化していた。

# v0.x implementation
self.db = TaskDB(self.db_path)

この設計には以下の課題がある：

1. 拡張性の欠如: SQLite 以外のデータベース（PostgreSQL, DuckDB, In-Memory DB等）を使いたくても、ライブラリのコードを書き換えない限り不可能である。
2. テストの制約: ユニットテスト時に、ファイルシステムに依存しないモックDBやオンメモリDBへの差し替えが困難である。

v1.0.0 では、ユーザー体験（DX）としての「手軽さ（パスを指定するだけ）」を維持しつつ、アーキテクチャレベルでの柔軟性を確保する必要がある。

判断基準

• Extensibility: ユーザーが独自の TaskDB 実装を注入 (Inject) できるようにする。
• Backward Compatibility / DX: 従来通りファイルパス（文字列）を渡すだけの初期化もサポートし、ライトユーザーの負担を増やさない。
• Testability: データベース層のモック化を容易にする。

検討した選択肢

• Option 1: 現状維持（SQLiteを内部でハードコード）。
• Option 2: db_path は維持しつつ、内部のファクトリで実装を切り替える。
• Option 3: Project に DB インスタンスを直接渡す Dependency Injection (DI) パターン。

決定事項

採用した選択肢: Option 3.

1. 抽象化: src/beautyspot/db.py に抽象基底クラス TaskDB を定義し、インターフェース（save, get, init_schema 等）を強制する。
2. 具象化: 従来のSQLite実装を SQLiteTaskDB として再定義する。
3. 注入 (DI): Project クラスのコンストラクタ引数を db_path: str から db: Union[str, TaskDB] に変更する。
   • str が渡された場合: 内部で SQLiteTaskDB(path) を生成する（Convenience）。
   • TaskDB が渡された場合: そのインスタンスをそのまま使用する（Injection）。

影響・結果

• Positive:
  • PostgreSQL や MySQL などのアダプタをユーザー側で実装し、Project(..., db=PostgresDB(...)) のように利用可能になる。
  • テスト時に MemoryTaskDB などを差し込むことで、高速かつクリーンなテストが可能になる。
• Negative:
  • db_path 引数が廃止（または db に統合）されるため、既存コードの引数名変更が必要になる（v1.0.0 での破壊的変更）。

ネイティブBLOBサポートを伴う全体的なMsgpackの採用

コンテキストと課題

ADR-0007 で MsgpackSerializer を導入しましたが、SQLiteへの保存方式について以下の課題が残っていました。

1. JSONの限界: 従来の TEXT カラム（JSON）ではバイナリデータを扱えず、Numpy配列などが保存できない。
2. Base64の非効率性: TEXT カラムに保存するために Msgpack を Base64 エンコードする案がありましたが、データサイズが約33%増加し、CPUコストもかかる。
3. 一貫性: 画像や動画などのバイナリデータも、可能な限り変換なしで「そのまま」扱いたい。

判断基準

• Performance: シリアライズ/デシリアライズ의 オーバーヘッド（Base64等）を最小化したい。
• Efficiency: ストレージ容量を無駄に消費したくない。
• Consistency: 小さいデータ（DB内）も大きいデータ（外部ファイル）も、同じ Msgpack フォーマットで統一したい。

検討した選択肢

• Option 1: Msgpack バイナリを Base64 エンコードして、既存の TEXT カラムに保存する。
• Option 2: データベースに BLOB カラムを追加し、Msgpack バイナリをそのまま保存する。

決定事項

採用した選択肢: Option 2.

1. Schema Change: Add BLOB Column

tasks テーブルに、バイナリデータをそのまま格納するための result_data (BLOB) カラムを追加します。

• 既存の result_value (TEXT) カラムは、ファイルパスやレガシーなJSONデータの保持用に継続利用する。
• マイグレーションは Project 初期化時に ALTER TABLE で自動的に行われる。

2. Msgpack Everywhere Strategy

データの保存先に関わらず、常に MsgpackSerializer を通過させます。

• save_blob=False (Direct Mode):
  • Msgpackバイナリを result_data (BLOB) カラム にそのまま保存する。
  • result_type は DIRECT_BLOB とする。
• save_blob=True (Blob Mode):
  • Msgpackバイナリを外部ファイル（.bin）として保存。
  • ファイルパスを result_value (TEXT) カラム に保存する。
  • result_type は FILE とする。

3. Size Guardrails (Unchanged)

save_blob=False であっても、閾値（デフォルト: 1MB）を超えるデータが渡された場合は、警告ログ (WARNING) を出力して save_blob=True の利用を促します。

影響・結果

• ポジティブ:
  • 最高効率: Base64エンコードが不要になり、データサイズとCPU負荷が最小化される。
  • 互換性: 既存の result_value カラムを維持するため、旧バージョンのキャッシュデータも読み込み可能。
• ネガティブ:
  • データベースのスキーマ変更（マイグレーション処理）が必要になる。
  • sqlite3 コマンドラインツール等で SELECT した際、中身がバイナリのため視認できない（ダッシュボード等のツールが必要）。

MsgpackとSHA-256を用いた正規化された入力シリアライズ

コンテキストと課題

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

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

判断基準

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

検討した選択肢

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

決定事項

採用した選択肢: Option 2.

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

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

影響・結果

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

命令型実行、スマートなデフォルト、およびワークスペース管理

コンテキストと課題

これまで beautyspot は、関数のキャッシュ化にデコレータ (@project.task) を使用する方法のみを提供していました。しかし、実際の利用シナリオにおいて以下の課題が浮き彫りになりました：

1. サードパーティライブラリの利用: ソースコードを変更できない関数（例: pandas.read_csv）や、外部APIクライアントのメソッドをキャッシュしたい場合、わざわざラッパー関数を定義する必要があり、記述が冗長になる。
2. アドホックな解析: ノートブック環境や一時的なスクリプトで試行錯誤する際、関数定義の手間がオーバーヘッドとなり、開発体験（DX）を損ねる。
3. リソース管理の曖昧さ: Project インスタンスが内部で保持する ThreadPoolExecutor が適切にシャットダウンされない場合、プロセスがハングするリスクがある。
4. ディレクトリの汚染: 生成されるデータベースファイル (.db) やBlobディレクトリ (blobs/) がプロジェクトルート直下に作成され、ディレクトリ構成が煩雑になる。
5. 設定の重複: 複数のタスクで「常にBlob保存したい」「特定のバージョンを一律適用したい」といった場合、都度引数を指定するのは DRY (Don't Repeat Yourself) 原則に反する。
6. None 結果のキャッシュ: time.sleep のように戻り値が None である関数をキャッシュしようとすると、キャッシュミスと誤認され再実行されてしまうバグが存在した。

判断基準

• Flexibility: ソースコードを変更できない外部関数やアドホックな処理に対しても、簡単にキャッシュを適用できること。
• Safety: 非同期タスクや Executor のリソース管理を確実に行い、プロセスのクリーンな終了を保証すること。
• Clutter-free: 生成されるキャッシュファイルを1箇所に集約し、プロジェクト構成をきれいに保つこと。
• Accuracy: None を返す関数も含め、あらゆる戻り値を正しくキャッシュできること。

検討した選択肢

• Option 1: 現状のデコレータ方式のみを維持し、ユーザーにラッパー関数の作成を求める。
• Option 2: 命令的な run メソッドの導入、ワークスペースディレクトリ（.beautyspot/）による集約、コンテキストマネージャによるリソース管理を統合的に実装する。

決定事項

採用した選択肢: Option 2.

以下の包括的なアーキテクチャ変更を行います。

1. 命令的実行メソッド (project.run) の導入

デコレータを使用せず、関数オブジェクトとその引数を渡すことで即座にキャッシュ付き実行を行う run メソッドを Project クラスに追加します。

result = project.run(func, arg1, arg2, _save_blob=True)

• 引数設計: キャッシュ制御用のオプション引数は、対象関数のキーワード引数 (kwargs) との衝突を避けるため、プレフィックス _ を付与します（例: _save_blob, _version, _content_type）。

2. コンテキストマネージャとリソース管理

Project クラスをコンテキストマネージャとして設計し、with ブロック内での利用を推奨パターンとします。これにより、ブロック終了時に確実に shutdown() が呼ばれ、スレッドプール等のリソースが解放されることを保証します。

3. 設定の階層化とスマートデフォルト

Project 初期化時にデフォルト設定を受け入れ、個別の実行時にそれを継承・上書きできる仕組みを導入します。優先順位は「個別指定 > プロジェクトデフォルト > システムデフォルト」とします。

4. ワークスペースディレクトリによる集約

すべての生成アーティファクト（DB、Blob）を、デフォルトで隠しディレクトリ .beautyspot/ 配下に集約します。また、初期化時に .gitignore を自動生成し、キャッシュファイルがバージョン管理に含まれるのを防ぎます。

5. 番兵オブジェクトによるキャッシュ判定

キャッシュヒットの判定において None を特別視せず、専用の番兵オブジェクト (CACHE_MISS) を導入することで、None を返す関数も正しくキャッシュ可能とします。

影響・結果

• ポジティブ:
  • 高い柔軟性: 既存のコードやライブラリ呼び出しに対して、ボイラープレートなしで即座にキャッシュを適用可能になった。
  • 安全なリソース管理: with 文の使用により、プロセスハングのリスクが大幅に低減した。
  • クリーンな環境: プロジェクトルートが汚れず、Git管理からの除外も自動化されたため、ユーザーの負担が減った。
  • 正確なキャッシュ: 副作用のみを目的とした関数（戻り値なし）も扱えるようになり、適用範囲が広がった。
• ネガティブ:
  • APIの複雑化: project.run の引数に特殊なプレフィックスルール（_）が導入されたため、ドキュメントでの周知が必要。
  • 後方互換性の注意: 引数処理の変更に伴い、内部実装での厳密なチェックが必要になった。

ProjectをSpotに、TaskをMarkに名前変更

コンテキストと課題

現在、beautyspot のメインエントリーポイントとして Project クラスが、タスク定義のデコレータとして @project.task が使用されています。しかし、これらの名称には以下の課題があります。

1. Project の曖昧さ: ユーザーにとって "Project" は、自身のソースコード全体やリポジトリを指す言葉であることが多いです。ライブラリの管理オブジェクトを Project と呼ぶことで、ユーザーのメンタルモデルとの衝突（「プロジェクトの中にプロジェクトがある？」）を招いています。
2. task の不一致: task は「仕事・課題」を表す名詞ですが、デコレータの役割は「関数を永続化対象として登録・設定する」という動的な作用です。名詞としての命名は、宣言的なデコレータの性質と完全に一致していません。
3. ブランド・アイデンティティの欠如: 現在の API は汎用的すぎて、このライブラリ特有の「黒子」や「美点（Beauty Spot）」というコンセプトがコード上で表現されていません。

判断基準

• Mental Model Alignment: ユーザーのプロジェクト構成とライブラリの管理単位を混同させないこと。
• Declarative API: デコレータの役割が「設定の付与（マーキング）」であることを直感的に伝えること。
• Brand Consistency: ライブラリ名 beautyspot と API の命名に一貫性を持たせること。

検討した選択肢

• Option 1: 現状維持（Project および task）。
• Option 2: Project を Spot に、task を mark にリネームする。

決定事項

採用した選択肢: Option 2.

ライブラリのコアとなる用語を再定義し、以下のリネームを行います。

1. Rename Project class to Spot

管理クラスの名前を Spot に変更します。これにより、「コード上の特定の場所（Spot）を管理する」というニュアンスを持たせ、ライブラリ名 beautyspot との一貫性を持たせます。

2. Rename @task decorator to @mark

デコレータ名を @spot.mark に変更します。これは "Marking a spot"（地点に印を付ける）というイディオムに基づいており、「この関数を管理対象としてマークする」という宣言的な意図を明確にします。

3. Keep run method as spot.run

命令的な実行メソッドである run は、名前を変更せずそのまま維持します。これは、「mark（宣言・静的）」と「run（実行・動的）」という役割分担を明確にするためです。

影響・結果

• ポジティブ:
  • 直感的なメンタルモデル: Spot と mark の組み合わせにより、「コード上の重要な箇所に印を付けて管理する」という思想が伝わりやすくなる。
  • 名前空間の明確化: 変数名 spot を使用することで、それが beautyspot のインスタンスであることが一目で分かる。
  • 一貫性: ライブラリ名とクラス名が一致し、ブランドとしての統一感が生まれる。
• ネガティブ:
  • 破壊的変更: 既存の v1.x 系コードとは互換性がなくなる。
  • 移行コスト: 既存ユーザーはコードの書き換えが必要となる。

遅延バインディングを伴うデコレータベースの型登録

コンテキストと課題

これまでの spot.register_type() は命令的であり、クラス定義と登録ロジックが分離してしまうため、凝集度が低いという課題がありました。 また、Pydantic モデルのようなクラスメソッド（例: cls.model_validate_json）をデコーダとして登録したい場合、デコレータ評価時にはまだクラスが未定義（NameError）であるため、綺麗に記述できないという技術的な制約がありました。

判断基準

• Developer Experience (DX): クラス定義の直上にシリアライズ設定を記述したい（Co-location）。
• Support for Modern Libraries: Pydantic など、クラスメソッドをファクトリとして使用するパターンを容易にサポートしたい。
• Safety: 循環参照や未定義エラーを回避しつつ、型安全に登録を行いたい。

検討した選択肢

• Option 1: 命令的な register_type() メソッドのみを提供する。
• Option 2: デコレータベースの register メソッドを追加し、decoder_factory による遅延バインディングを導入する。

決定事項

採用した選択肢: Option 2.

Spot クラスに register デコレータメソッドを追加し、decoder_factory による遅延バインディング を導入します。

Technical Details / 技術詳細

@spot.register(
    code=10,
    encoder=lambda obj: ...,
    decoder_factory=lambda cls: cls.deserialize  # Class is passed here after definition
)
class MyModel:
    ...

1. register デコレータは、対象クラスの定義完了後（デコレート時）に実行される。
2. decoder_factory が指定されている場合、生成された cls オブジェクトを引数としてファクトリを実行し、実際の decoder 関数を取得する。
3. 取得した decoder を用いて、既存の register_type バックエンドに登録する。

影響・結果

• ポジティブ:
  • ユーザーはクラス定義と登録を1箇所にまとめられる。
  • 自己参照を含むクラス（自分自身を返すクラスメソッドなど）の登録が容易になる。
• ネガティブ:
  • decoder と decoder_factory という2つの引数が増え、APIが少し複雑になる（ドキュメントでの補完が必要）。

命令型実行のための厳密なスコープ管理（ランタイムガード）

コンテキストと課題

spot.cached_run() コンテキストマネージャを使用すると、ユーザーは一時的に関数のキャッシュ挙動を適用できます。しかし、Python の with 文のスコープルールにより、ブロック内でバインドされた変数（例: with ... as task:）はブロック終了後もアクセス可能です。

これにより、ユーザーが特定のコンテキスト設定（version="v1" や一時的なストレージ設定など）を持つ関数ラッパーを、意図しない場所で再利用してしまうリスクがあります。これは微妙なバグやリソースリークの原因となります。

判断基準

• Safety: 意図しないスコープ外での「古い」または「コンテキスト固有の」ラッパーの使用を排除すること。
• Clarity: キャッシュ挙動が厳密に一時的なものであるというメンタルモデルを強制すること。
• Resource Management: 短命な spot インスタンスや注入されたインスタンスをより安全に使用できるようにすること。

検討した選択肢

• Option 1: ガードを実装せず、ユーザーの注意に任せる。
• Option 2: Runtime Guard パターンを導入し、ブロック外での呼び出しを制限する。

決定事項

採用した選択肢: Option 2.

ScopedMark コンテキストマネージャに Runtime Guard パターンを実装します。

1. State Tracking: コンテキストマネージャはアクティブ状態のフラグを保持する。
2. Wrapper Guard: cached_run から返される関数は、実行前にこのフラグをチェックするガードでラップされる。
3. Fail Fast: ラップされた関数が with ブロックの外で呼び出された場合、即座に RuntimeError を送出する。

影響・結果

• ポジティブ:
  • 意図しないスコープ外での使用によるリスクを排除できる。
  • 「キャッシュマジック」は厳密に一時的なものであるという確信が持てる。
  • 関数参照が使用直後に無効になるため、リソース管理が安全になる。
• ネガティブ:
  • ブロック内での関数呼び出しごとに、極小のオーバーヘッド（ブールフラグのチェック）が発生する。
  • ラップ処理の追加により、ScopedMark の実装がわずかに複雑になる。

対話的な削除とクリーンアップポリシー

コンテキストと課題

beautyspot は「試行錯誤の高速化」を掲げていますが、ユーザーが失敗した実験結果（キャッシュ）を即座に破棄する手段が Dashboard 上に存在しませんでした。 また、キャッシュ削除のロジックが cli.py に直接実装されており、Core API (Spot クラス) として提供されていないため、プログラムからの制御やテストが困難な状態でした。

加えて、削除機能を実現するには BlobStorageBase (Storage backend) に物理ファイルを削除するインターフェースが必要ですが、これまでの定義には save と load しか存在しませんでした。

判断基準

• User Experience: Dashboard 上で「結果を見て、即座に消して、やり直す」というループを実現したい。
• Consistency: CLI, Dashboard, Python Script すべてで同一の削除ロジックを利用したい。
• Cleanliness: DBレコードを消した際に、対応する Blob ファイルも確実に消去したい。

検討した選択肢

• Option 1: 手動での削除（OS コマンドや DB の直接編集）をユーザーに委ねる。
• Option 2: Core API に delete メソッドを追加し、Storage インターフェースを拡張して、Dashboard からも操作可能にする。

決定事項

採用した選択肢: Option 2.

1. Core API への delete メソッドの追加 Spot.delete(cache_key) を正式な API として追加します。このメソッドは、「DBレコードの削除」と「Blobファイルの削除」をアトミック（ベストエフォート）に行う責任を持ちます。

2. Storage Interface への拡張 BlobStorageBase 抽象基底クラスに delete(location) メソッドを追加します。

3. Breaking Change: ユーザーが独自の Storage Backend を実装している場合、delete メソッドの実装が必要となります。

4. Idempotency: ファイルが既に存在しない場合でもエラーを送出せず、静かに終了する（冪等な挙動）ことを推奨実装とします。

5. Dashboard への削除機能の露出 Dashboard に削除ボタンを配置します。誤操作を防ぐため、確認ダイアログを経由する UI とし、Spot.delete を呼び出します。

影響・結果

• ポジティブ:
  • ユーザーは Dashboard から離れることなく、不要なキャッシュを整理できる。
  • キャッシュ削除ロジックが一元化され、メンテナンス性が向上する。
  • 将来的な「自動ローテーション」機能の基盤となる。
• ネガティブ:
  • BlobStorageBase を継承したカスタムクラスを持つ既存ユーザーコードは、delete メソッドの実装が必要になる。
  • リリースノートでの周知が必須となる規模の変更である。

title: Nested Msgpack Protocol via Serializer Wrapping status: Accepted date: 2026-02-02 context: Improving DX for Custom Types

シリアライザラッパーによるネストされたMsgpackプロトコル

コンテキストと課題

これまでは、カスタム型のエンコーダは ExtType の仕様に合わせて「生のバイト列」を返す必要がありました。 これにより、ユーザーは msgpack ライブラリを直接操作する必要があり、Pydantic モデルなどの扱いが煩雑になっていました。

判断基準

• Simplicity: ユーザー関数は、ただの型変換（Obj <-> Dict）のみに集中すべきである。
• Encapsulation: バイナリ化（Pack/Unpack）の責務はライブラリ側が負うべきである。

検討した選択肢

• Option 1: エンコーダが生のバイト列（bytes）を返し、デコーダがそれを受け取る（旧仕様）。
• Option 2: シリアライザラッピングを採用。エンコーダは Python オブジェクト（Dict 等）を返し、ライブラリが内部で Msgpack 化して保持する。

決定事項

採用した選択肢: Option 2.

Serializer Wrapping (Nested Protocol) を採用します。

1. MsgpackSerializer は、ユーザー定義のエンコーダ/デコーダに対するラッパー（Wrapper）として機能する。
2. Encode時: エンコーダが返したオブジェクト（中間表現）を、ライブラリが自動的に packb して ExtType に格納する。
3. Decode時: ExtType のデータを、ライブラリが自動的に unpackb してからデコーダに渡す。
4. これにより、ユーザーは import msgpack をする必要がなくなり、直感的な実装が可能になる。

影響・結果

• ポジティブ:
  • Pydantic v2 や Dataclasses のサポートが極めて容易になる。
  • 内部的に再帰呼び出しを行うため、カスタム型のネストも自動的に解決される。
• ネガティブ:
  • 内部での再帰的な Pack/Unpack による、わずかなパフォーマンス上のオーバーヘッドが発生する可能性がある。

テスト戦略の拡張：高レベル統合テストの導入

コンテキストと課題

現在、beautyspot のテストスイート（tests/）は、主にユニットテストや特定の機能（シリアライザー、リミッターなど）に焦点を当てたテストで構成されている。これらは個々のコンポーネントの正確性を保証する上では有効だが、以下の課題がある：

1. 連携の検証不足: 複数のタスクが依存関係を持つパイプライン（Load -> Process -> Train）において、バージョニングやキャッシュの伝播が正しく行われるかどうかの検証が不十分である。
2. 実環境との乖離: 多くの場合、CliRunner やモックオブジェクトを使用しているため、実際のファイルシステムや SQLite データベースに対する副作用（ファイルの生成、削除、ロック競合など）を検証できていない。
3. ユーザー体験の保証: CLI コマンド（stats, clean など）と Python API による実行結果の整合性を、ユーザーの一連の操作フローとして検証する仕組みがない。

「個々の部品は正しいが、組み合わせると意図した通りに動かない」という統合レベルのバグを防ぐため、テスト戦略を見直す必要がある。

判断基準

• Reliability: ユーザーが実際に構築するような複雑なパイプラインにおいても、キャッシュや依存関係解決が正しく動作することを保証したい。
• Refactoring Safety: 内部実装（例: DBスキーマや保存ロジック）を変更した際に、ユーザーから見た挙動が変わっていないことを高いレベルで検知したい。
• Documentation: テストコード自体を「ユーザーがどのようにライブラリを使うべきか」を示す実行可能なドキュメント（Executable Documentation）として機能させたい。

検討した選択肢

• Option 1: 現状維持（ユニットテストの拡充）。
  • Pros: 実行が高速。
  • Cons: コンポーネント間の連携ミスや、実IOに伴う問題を見逃すリスクが高い。
• Option 2: 手動QA手順書の作成。
  • Pros: 実装コストが低い。
  • Cons: 再現性が低く、CIで自動化できないため、リリースのボトルネックになる。
• Option 3: tests/integration/ ディレクトリを新設し、E2E（End-to-End）シナリオテストを導入する。
  • Pros: 実際のユーザー利用に近い形で品質を保証できる。
  • Cons: IOを伴うため実行時間が長くなる。セットアップがやや複雑になる。

決定事項

採用した選択肢: Option 3.

テストピラミッドの上層として、以下の戦略でインテグレーションテストを導入する：

1. ディレクトリ構成: tests/integration/ を新設し、ユニットテストとは明確に分離する。
2. テスト範囲 (Scope):
   • Pipeline E2E: データのロードから学習までの一連のタスクフローを定義し、初回の実行、キャッシュヒット、バージョニングによる部分再計算（依存関係の解決）を検証する。
   • CLI Integration: Python コードで生成された DB ファイルに対し、beautyspot CLI コマンド（stats, list 等）を実行し、出力が正しいことを検証する。
3. 技術的制約:
   • モックの使用は最小限に留め、原則として実ファイル（SQLite DB, Blobファイル）を使用する（tmp_path フィクスチャを活用）。
   • beautyspot.Spot クラスを実際にインスタンス化し、ユーザーコードと同じインターフェース経由で操作を行う。

Example Scenario / 想定シナリオ

def test_ml_pipeline_lifecycle(spot_env):
    # 1. Pipeline Definition (Load -> Process -> Train)
    # 2. Initial Run (Assert all executed)
    # 3. Cache Hit Run (Assert none executed)
    # 4. Version Upgrade of Middle Task (Assert downstream re-executed)
    # 5. CLI "stats" command check (Assert DB integrity)

影響・結果

• ポジティブ:
  • リリース前の信頼性が大幅に向上する。特に「キャッシュが効きすぎて更新されない」「意図せず再計算される」といった複雑なバグを検知しやすくなる。
  • CLI と Python API の互換性が常に保証される。
• ネガティブ:
  • テスト実行時間が増加する（ファイルIOを含むため）。
  • テストコードのメンテナンスコストが若干増加する。

タスクごとのシリアライザの上書き

コンテキストと課題

プロジェクト全体としては安全性と互換性の観点から msgpack を標準シリアライザとしています。 しかし、探索的データ分析（EDA）やプロトタイピング、あるいは msgpack でのシリアライズが困難なサードパーティ製オブジェクトを扱う特定のタスクにおいては、Python標準の pickle のような柔軟なシリアライザを局所的に使用したいというニーズがあります。

判断基準

• Flexibility: 標準シリアライザで扱いにくい特殊なオブジェクトに対して、最適な保存方法を選択できること。
• Locality: プロジェクト全体の設定（セキュリティポリシー等）を損なうことなく、特定の箇所だけで設定を上書きできること。
• Fault Tolerance: オーバーライドされたシリアライザでエラーが発生しても、再計算によって実行を継続できること。

検討した選択肢

• Option 1: グローバルなシリアライザ設定のみを提供し、個別の変更は認めない。
• Option 2: Spot.mark() および Spot.cached_run() に serializer 引数を追加し、局所的なオーバーライドを可能にする。

決定事項

採用した選択肢: Option 2.

1. Override Mechanism: Spot.mark() および Spot.cached_run() に、オプショナル引数 serializer を追加します。
2. Protocol: ユーザーは dumps(obj) -> bytes および loads(bytes) -> obj メソッドを持つ任意のオブジェクトを渡すことができます。
3. Fallback Behavior: 指定されたシリアライザでデシリアライズに失敗した場合、ADR-0003 の方針に従い、キャッシュ破損として扱い、タスクを再実行します。

影響・結果

• ポジティブ:
  • ユーザーはプロジェクト全体の設定を変更することなく、必要な箇所だけで pickle 等の機能を利用できる。
  • キャッシュが読み込めなくなった場合も、自動的に再計算されるため、開発体験（DX）が損なわれない。
• ネガティブ:
  • pickle を使用したタスクは、異なる環境間や長期間の保存において互換性が保証されない。
  • Spot.register() で登録したカスタム型変換は、オーバーライドされたシリアライザには適用されない。

タスククリーンアップのための寛容な削除ポリシー

コンテキストと課題

spot.delete(key) 機能は、特定のタスクに関連する「キャッシュレコード（DB）」と「実データ（Blob/File）」の両方を削除することを目的としています。

ローカルファイルシステムやS3などの外部ストレージにおいて、Blobの削除操作は様々な理由（ネットワーク障害、一時的な権限エラー、ファイルが既に手動で削除されている等）で失敗する可能性があります。

このとき、厳密な整合性を求めて「Blob削除に失敗したらDBレコードの削除もロールバック（中断）する」という実装にすると、以下の問題が発生します：

1. ゾンビレコード: 物理ファイルが見つからないだけなのに、DBからレコードを消せず、ユーザーは永遠にそのタスクを「無効化」できない。
2. 再計算の阻害: 破損したキャッシュエントリが残り続けることで、新しい計算結果での上書きや、クリーンな状態からの再実行が妨げられる。

判断基準

• Guaranteed Invalidation: ストレージの状態に関わらず、ユーザーが「削除」を指示したタスクを確実に管理対象から外すこと。
• Workflow Continuity: 物理ファイルの欠落などの非本質的なエラーで、ユーザーのワークフローを中断させないこと。
• Consistency Management: DB とストレージの乖離を最小限に抑えつつ、システムの健全性を維持すること。

検討した選択肢

• Option 1: 厳密な削除。Blob の削除に失敗した場合は例外を送出し、DB のレコード削除も行わない。
• Option 2: 寛容な削除（Tolerant Deletion）。DB レコードの削除を優先し、Blob 削除時のエラーはログ出力に留めて処理を継続する。

決定事項

採用した選択肢: Option 2.

削除操作において 「メタデータの削除を優先する」 ポリシーを採用します。

1. まず、Blob（実データ）の削除を試みる。
2. Blobの削除中に例外が発生した場合、処理を中断せず、WARNING レベルのログを出力してエラーを捕捉する。
3. Blob削除の成否に関わらず、DB上のタスクレコードの削除を必ず実行する。

影響・結果

• ポジティブ:
  • ユーザーはストレージの状態に関わらず、beautyspot の管理下からタスクを確実に削除できる。
  • 「ファイルが見つからない」といった些細なエラーでワークフローが止まることを防げる。
• ネガティブ:
  • 孤立ファイル (Orphaned Blobs): DBレコードは削除されたが、ストレージ上にファイルだけが残るケースが発生しうる。
  • 対策として、別途ガベージコレクション（GC）ツールやストレージ側のライフサイクルポリシーでの対処が必要になる場合がある。

コードの可視化と品質メトリクス戦略

コンテキストと課題

プロジェクトの規模拡大に伴い、以下の課題が発生しています：

1. 構造の把握困難: モジュール間の依存関係が複雑化し、全体像を掴みにくい。
2. 品質の定量化: コードの複雑さが主観で語られており、客観的なリファクタリング基準がない。
3. アーキテクチャの健全性: 「安定依存の原則（SDP）」が守られているか（不安定なモジュールが安定したモジュールに依存していないか）を確認する手段がない。

判断基準

• Objectivity: リファクタリングの優先順位を、数値に基づく客観的な基準で決定すること。
• Visibility: モジュール間の依存関係を視覚化し、設計上の「逆流」を容易に発見できること。
• Automation: 開発フロー（CI/CD や Makefile）に組み込み、常に最新のメトリクスを維持すること。

検討した選択肢

• Option 1: 手動のコードレビューのみで品質を管理する。
• Option 2: Radon, Pydeps, および独自スクリプトを導入し、メトリクス計測と可視化を自動化する。

決定事項

採用した選択肢: Option 2.

以下のツールを導入し、開発フローに統合します。

1. Radon:
   • 循環的複雑度 (Cyclomatic Complexity) と保守性指数 (Maintainability Index) を計測する。
2. Pydeps:
   • モジュール間のインポート依存関係を可視化するグラフ（SVG）を生成する。
3. Custom Stability Analyzer:
   • 不安定度 ($I$) を算出する独自スクリプトを tools/ に配置する。
   • Graphviz を用いて、安定度に基づいた色分け（青＝安定、赤＝不安定）を行ったアーキテクチャ図を生成する。

影響・結果

• ポジティブ:
  • リファクタリングの優先順位を数値に基づいて決定できる。
  • 生成された図により、新規参画者のオンボーディングが高速化される。
  • 設計原則（SDP）違反を視覚的に検知できる。
• ネガティブ:
  • 実行環境に graphviz (システムパッケージ) のインストールが必須となる。

シングルディスパッチによる複雑なモジュールのリファクタリング

コンテキストと課題

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

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

判断基準

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

検討した選択肢

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

決定事項

採用した選択肢: Option 2.

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

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

影響・結果

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

メンテナンス操作のためのサービスレイヤー

コンテキストと課題

現在、src/beautyspot/cli.py には以下のビジネスロジックが直接記述されています： 1. Pruning: タイムスタンプに基づく古いタスクの削除。 2. Cleaning: 孤立した Blob ファイルの特定と削除（ガベージコレクション）。

これらのロジックは sqlite3 ドライバに直接アクセスしたり、ファイルパスを操作したりしており、TaskDB や BlobStorageBase の抽象化をバイパスしています。これにより、CLI が SQLite やローカルファイルストレージの詳細に密結合し、他のインターフェース（スクリプトや Web UI）から同じロジックを再利用できないという問題が発生しています。また、S3 などの外部ストレージに対する「掃除」機能の実装も困難になっています。

判断基準

• Decoupling: CLI を特定のデータベース実装やファイルシステム詳細から切り離すこと。
• Reusability: メンテナンスロジック（整理や掃除）をプログラムから、あるいは Dashboard からも利用可能にすること。
• Abstraction Support: S3 などの異なるストレージバックエンドでも、一貫したガベージコレクションが行えるようにすること。

検討した選択肢

• Option 1: メンテナンスロジックを CLI に残したままにする。
• Option 2: 全てのロジックを Spot クラスに追加する。
• Option 3: 専用のサービスレイヤー MaintenanceService を新設し、管理ロジックを分離する。

決定事項

採用した選択肢: Option 3.

メンテナンスロジックを cli.py から抽出し、専用の MaintenanceService (src/beautyspot/maintenance.py) に移動します。

Spot クラスはアプリケーションの実行コンテキストとキャッシュ制御に集中させ、メンテナンス（行政的タスク）は別の関心事として分離します。

• MaintenanceService: レコードの整理、孤立した Blob の掃除、履歴の照会などを担当。TaskDB と BlobStorageBase を調整（Orchestrate）する。
• Spot: 実行時の登録 (mark) と実行 (run) に専念する。

影響・結果

• ポジティブ:
  • 関心の分離: 実行時ロジック (Spot) を軽量に保ちつつ、管理ロジックを独立して進化させることができる。
  • テスト容易性: CLI を起動することなく、メンテナンスロジックのユニットテストが可能になる。
  • 再利用性: 整理や掃除を他のスクリプトや Dashboard からトリガーできる。
  • 抽象化の恩恵: バックエンドが list_keys 等を実装していれば、S3 等でも自動的に GC がサポートされる。
• ネガティブ:
  • インターフェースの拡張: メンテナンス支援のため、TaskDB や BlobStorageBase に新たなメソッド（list_keys, get_blob_refs 等）を追加する必要がある。

ノンブロッキングなキャッシュの永続化とタスク追跡

コンテキストと課題

大規模なデータのシリアライズや、S3 等のリモートストレージへの保存処理は、ユーザーのメインロジックの実行を妨げる（ブロッキング）要因となっていました。「インフラとしてのキャッシュ処理がユーザーを待たせない」という設計思想を強化する必要があります。

判断基準

• Latency Reduction: キャッシュの保存処理（特に入出力の重い処理）が、メインスレッドの実行速度を低下させないこと。
• Data Integrity: バックグラウンド保存であっても、プログラムの終了前には全ての保存が完了していることを保証し、データロストを防ぐこと。
• API Reusability: Spot インスタンスを何度も再利用でき、かつリソースの適切なクリーンアップ（フラッシュ）が行えること。

検討した選択肢

• Option 1: 全ての保存処理をメインスレッドで同期的に行う。
• Option 2: 保存処理をバックグラウンド（Fire-and-Forget）で実行し、タスク追跡と with ブロックによる自動フラッシュの仕組みを導入する。

決定事項

採用した選択肢: Option 2.

キャッシュの保存処理をバックグラウンドで実行し、かつリソースの整合性を保つためのライフサイクル管理を導入します。

1. wait=False モードの導入: @spot.mark や cached_run に wait オプションを追加し、保存完了を待たずにメインロジックに結果を返すことを可能にします。
2. タスク追跡メカニズム: 実行中のバックグラウンドタスク（Future）を内部のセットで追跡します。
3. Flush (非破壊的待機) の導入: with spot: ブロックを抜ける際に、全てのバックグラウンドタスクの完了を待機する（Flush）処理を実行します。
4. 再利用性の確保: コンテキストを抜けても Executor は即座にシャットダウンせず、Spot インスタンスを繰り返し安全に利用可能にします。

影響・結果

• ポジティブ:
  • レイテンシの改善: 保存処理がバックグラウンド化され、ユーザーの体感速度が向上する。
  • データ整合性の保証: with ブロックやプロセス終了時に未完了タスクを必ず待機するため、データの整合性が保たれる。
  • 直感的な API: グローバルに定義したオブジェクトを、何度も安全に「フラッシュ」しながら使い回せる。
• ネガティブ:
  • 例外ハンドリングの複雑化: バックグラウンドで発生したエラーは即座に呼び出し元へ伝播しないため、ログによる通知に依存することになる。

プロトコルベースのシリアライザ登録

コンテキストと課題

beautyspot では、@spot.register デコレータを使用してカスタム型を登録できます。 当初の実装では、Spot クラス内でシリアライザが MsgpackSerializer のインスタンスであるかどうかを明示的にチェックしていました。

if isinstance(self.serializer, MsgpackSerializer):
    self.serializer.register(...)

これは、高レベルの Spot クラスを特定の具象クラス (MsgpackSerializer) に結合させており、依存関係逆転の原則 (Dependency Inversion Principle) に違反していました。その結果、カスタム型登録をサポートする他のシリアライザ（将来的な JsonSerializer やカスタムラッパーなど）を使用することが不可能でした。

判断基準

• Decoupling: Spot クラスを特定のライブラリ（msgpack）や実装から切り離すこと。
• Extensibility: ユーザーが独自のシリアライザを実装し、かつカスタム型登録機能も維持できるようにすること。
• Interface Segregation: 基本的なシリアライズ機能と、型登録機能という異なる責務を明確に分離すること。

検討した選択肢

• Option 1: 具象クラスに対する isinstance チェックを維持する。
• Option 2: 構造的部分型（Protocol）を導入し、インターフェースに基づくチェックに切り替える。

決定事項

採用した選択肢: Option 2.

beautyspot.serializer に TypeRegistryProtocol を導入します。

1. Define Protocol: 型登録に必要な register メソッドのシグネチャを規定するプロトコルを定義します。
2. Decoupling: Spot クラスは、具象クラスではなくこのプロトコルに対して適合性チェックを行うように変更します。
3. Interface Segregation: 基本的な SerializerProtocol (dump/load) と TypeRegistryProtocol を分離し、型登録をサポートしないシリアライザも許容できるようにします。

影響・結果

• ポジティブ:
  • コアロジックが msgpack から解放され、TypeRegistryProtocol に従う任意のシリアライザを使用可能になった。
  • モックを使用したテストが容易になった。
• ネガティブ:
  • シリアライザの実装者は、プロトコルで定義された register メソッドのシグネチャを正確に遵守する必要がある。

デフォルトの依存性注入のためのファクトリ関数

コンテキストと課題

v2.0 以降、beautyspot は依存性注入 (DI) アーキテクチャを採用しました。Spot クラス（core.py）の初期化には、TaskDB, Serializer, Storage の各インスタンスを明示的に渡す必要があります。

これはテスト容易性と柔軟性の観点では優れていますが、単に「すぐに使い始めたい」だけのユーザーにとっては、初期化が非常に冗長になってしまうという課題がありました。

# 一般的なスクリプトには冗長すぎる
db = SQLiteTaskDB(...)
storage = LocalStorage(...)
serializer = MsgpackSerializer()
spot = Spot(name="app", db=db, storage=storage, serializer=serializer)

判断基準

• Developer Experience (DX): ライトユーザーが最小限の設定（名前のみなど）で即座に開始できること。
• Clean Architecture: core.py の Spot クラスを具象クラス（SQLite 等）の詳細から保護し、ピュアな状態に保つこと。
• Flexibility: 高度なユーザーが引き続き任意のコンポーネントを注入できる余地を残すこと。

検討した選択肢

• Option 1: ユーザーに常に全ての DI コンポーネントを手動で提供させる。
• Option 2: Spot.__init__ の引数にデフォルト値（具象クラス）を設定する。
• Option 3: __init__.py でファクトリ関数 Spot を提供し、そこでデフォルトの組み立てを行う。

決定事項

採用した選択肢: Option 3.

beautyspot/__init__.py において、具象クラスのインスタンス化を伴うファクトリ関数 Spot を公開します。

# beautyspot/__init__.py
def Spot(name: str, db=None, ...):
    resolved_db = db or SQLiteTaskDB(...)
    # ... 他の解決ロジック ...
    return _Spot(name, db=resolved_db, ...)

これにより、ライブラリのトップレベルからインポートされる Spot は関数となり、内部で core.py の _Spot クラスを組み立てて返します。

影響・結果

• ポジティブ:
  • "Opinionated Defaults, Flexible Internals": 初心者は1行で初期化でき、上級者はカスタムコンポーネントを注入できる。
  • コアとなる _Spot クラスが、SQLiteTaskDB などの具象実装をインポートする必要がなくなる（関心の分離）。
• ネガティブ:
  • 公開シンボル Spot がクラスではなく関数になるため、Spot を直接継承することが難しくなる。継承が必要な場合は core から _Spot をインポートする必要があるが、本ライブラリでは継承よりもコンポジションを推奨するため、許容範囲とする。

実践的なCLIリファクタリングポリシー

コンテキストと課題

quality_report.md において、src/beautyspot/cli.py 内の複数の関数（show_cmd, prune_cmd, stats_cmd）が循環的複雑度（CC）で Rank C の警告を受けています。一般的にプロジェクトでは CC の低減を推奨していますが、CLI モジュールに関してはその優先度と費用対効果を再検討する必要があります。

判断基準

• Efficiency: リファクタリングのリソースを、ユーザーに直接影響するコアロジックに優先的に配分すること。
• Readability: CLI コマンドの「上から下への命令的フロー」を維持し、挙動の追いやすさを損なわないこと。
• Architectural Impact: 依存関係の末端にある CLI モジュールの複雑さが、システム全体の安定性に与える影響を考慮すること。

検討した選択肢

• Option 1: 厳格なリファクタリング。すべての Rank C 関数を Rank A/B になるまで分解する。
• Option 2: 戦略的許容。表示ロジックに起因する複雑さは許容し、現状の構造を維持する。

決定事項

採用した選択肢: Option 2.

CLI モジュールの Rank C スコアについては、以下の理由から「即時の抜本的なリファクタリングは行わず、現状の構造を維持する」ことを決定しました。

• 表示ロジックの特性: cli.py の複雑さは、データ取得後の表示フォーマット分岐（Rich ライブラリによる出力制御）に集中しており、純粋なビジネスロジックの複雑さとは性質が異なります。
• 設計上の影響の小ささ: cli.py は依存関係の末端に位置しており、他モジュールへの波及効果がありません。
• 可読性の維持: CLI コマンドは、過度に抽象化されるよりも命令的に記述されている方が挙動を追いやすい場合があります。

影響・結果

• ポジティブ:
  • コアロジック（cachekey.py など）のリファクタリングにリソースを集中できる。
  • 不要な抽象化による「コードの追いづらさ」を回避できる。
• ネガティブ:
  • 品質レポート上の警告は残り続ける。
  • 将来的にコマンドがさらに肥大化した場合には、改めて分割を検討する必要がある。

CLIのスコープ定義と明示的なストレージリンク

コンテキストと課題

beautyspot の clean コマンドやガベージコレクション機能は、DBファイルとBlobストレージディレクトリの対応関係が「自明」であることを前提としています。標準構成（.beautyspot/ 配下）ではこの前提は成立しますが、ユーザーがカスタムパスを設定したり、外部バックエンド（S3等）を使用した場合、CLIツールは安全に依存関係を特定できません。この状態で推測に基づく削除を行うと、誤って無関係なデータを削除するリスクがあります。

判断基準

• Data Safety: 管理対象外のデータや、他のプロジェクトが使用しているデータを誤って削除しないこと。
• Predictability: CLI ツールがどの範囲までを安全に管理できるかを明確に定義すること。
• Extensibility: 将来的にカスタム構成であっても安全にメンテナンスが行えるような道筋を立てること。

検討した選択肢

• Option 1: パス構造や設定から対応関係を推測し、ベストエフォートでクリーンアップを試みる。
• Option 2: CLI の自動クリーンアップ機能を標準構成に限定し、カスタム構成についてはユーザー管理とする。あわせてメタデータによるリンクを将来的に導入する。

決定事項

採用した選択肢: Option 2.

1. CLI Scope Limitation (Policy)

CLIが提供する「ストレージの自動クリーニング・削除機能」のサポート範囲を、標準ディレクトリ構成（.beautyspot/ 配下）を使用しているプロジェクト に限定します。カスタム構成を利用している場合は、CLI による自動削除は保証されず、ユーザー自身の責任で管理を行う必要がある旨を明記します。

2. Explicit Storage Linkage (Roadmap)

「対応関係が自明でない」問題を根本解決するため、将来のバージョンで TaskDB内に使用しているStorageの情報をメタデータとして記録する 仕組みを導入します。DB初期化時に storage_uri を保存し、メンテナンス時に「操作対象のDBが参照しているストレージと、今操作しようとしている実体が一致するか」を検証可能にします。

影響・結果

• ポジティブ:
  • 安全性: 推測による誤削除を確実に防ぐことができる。
  • 明確な責任分界点: ツールが面倒を見る範囲と、ユーザーが管理すべき範囲が明確になる。
  • 将来の拡張性: メタデータ記録が実装されれば、カスタム構成でも安全なGCが可能になる。
• ネガティブ:
  • ユーザーの負担: カスタム構成を利用する上級ユーザーは、beautyspot clean などの恩恵をフルには受けられない場合がある。

再帰的なストレージクリーンアップとゾンビプロジェクトの回収

コンテキストと課題

これまでの beautyspot clean コマンドの実装には、以下の課題がありました。

1. ディレクトリの残留: clean コマンドは個別のファイル削除のみを行い、空になったディレクトリを削除していませんでした。
2. 隠しファイルの阻害: macOS の .DS_Store などのシステムファイルが存在する場合、ディレクトリが空とみなされず、削除できないケースがありました。
3. ゾンビプロジェクト: ユーザーが手動で DB ファイル (.db) のみを削除した場合、対応する Blob ディレクトリが管理外のゴミ（ゾンビプロジェクト）として残り続け、削除する手段がありませんでした。

判断基準

• Complete Cleanup: 不要なファイルだけでなく、空のディレクトリ構造も含めて完全に削除し、ファイルシステムをクリーンに保つこと。
• Robustness: システム生成ファイル（.DS_Store 等）に惑わされず、意図した通りにクリーンアップを実行できること。
• Garbage Collection: メタデータ（DB）を失った実データ（Blob）を検出し、安全に一括削除できること。

検討した選択肢

• Option 1: ファイル削除のみを継続し、ディレクトリの整理はユーザーに任せる。
• Option 2: 2段階のクリーンアップ戦略（ファイル削除 ＋ 再帰的な空ディレクトリ整理）と、ゾンビプロジェクト回収用の gc コマンドを導入する。

決定事項

採用した選択肢: Option 2.

ストレージのクリーンアップ戦略を以下のように刷新します。

1. Two-Phase Cleanup Strategy (clean command)

clean コマンドを2段階に分割します。 * Phase 1 (File Deletion): DB参照のない孤立ファイルを削除。 * Phase 2 (Directory Pruning): LocalStorage に prune_empty_dirs() メソッドを追加し、再帰的に空ディレクトリを一括削除。

2. Robust Directory Pruning

システム生成ファイル（.DS_Store, Thumbs.db, desktop.ini）のみが存在する場合、それらを「実質的な空」とみなし、強制的に削除した上で親ディレクトリを削除します。

3. Zombie Project Garbage Collection (gc command)

DBファイルが失われたプロジェクトを回収するための gc コマンドを実装します。対応する .db ファイルが存在しないディレクトリを「ゾンビプロジェクト」と判定し、shutil.rmtree で強制的に一括削除します。

影響・結果

• ポジティブ:
  • 完全なクリーンアップ: ユーザーはコマンド一つで不要なディレクトリ構造まで一掃できる。
  • 運用性の向上: 手動操作で発生した残骸を簡単に解消できる。
  • 責務の分離: ファイル削除とディレクトリ整理を分離し、OS 固有の処理を Storage クラス内に隠蔽できた。
• ネガティブ:
  • IOオーバーヘッド: os.walk による再帰探索を行うため、ファイル数が膨大な場合にオーバーヘッドが発生する。

宣言的ストレージポリシー

コンテキストと課題

これまでの beautyspot では、関数の実行結果を Blob ストレージ（ファイル）に保存するか、DB のレコードに直接埋め込むかは、ユーザーが save_blob=True フラグで明示的に指定する必要がありました。 また、データサイズが大きい場合に警告を出す機能はありましたが、自動的に対処する機能はありませんでした。これにより、ユーザーはデータのサイズを予測してフラグを管理するという負担を強いられていました。

判断基準

• Automation: データサイズに応じて最適な保存先（DB または Blob）を自動的に選択し、ユーザーの負担を軽減すること。
• Declarative Configuration: 「1MB以上はファイルに保存する」といったルールを宣言的に記述できるようにすること。
• Separation of Concerns: キャッシュキー生成（Identity）と保存方式（Persistence）の責務を明確に分離すること。

検討した選択肢

• Option 1: 引き続きユーザーによる手動の save_blob フラグ管理に任せる。
• Option 2: 宣言的な StoragePolicy プロトコルを導入し、データ内容に基づいて自動的に保存方式を決定する仕組みを構築する。

決定事項

採用した選択肢: Option 2.

ストレージ保存方式の決定ロジックを抽象化した StoragePolicy プロトコルを導入します。

1. StoragePolicy Interface:

   • should_save_as_blob(data: bytes) -> bool を持つプロトコルを定義します。
   • 配置場所は src/beautyspot/storage.py とし、ストレージ関連の責務を凝集させます。

2. Standard Implementations:

   • ThresholdStoragePolicy: 指定したバイト数を超えた場合に Blob 保存を選択する（推奨デフォルト）。
   • WarningOnlyPolicy: 従来動作互換。Blob 化はせず、閾値超えでログ警告のみ行う。

3. Precedence (優先順位):

   • 優先度1: 関数ごとの明示的指定 (@mark(save_blob=...))。
   • 優先度2: ポリシーによる自動判定。

影響・結果

• ポジティブ:
  • ユーザーは個々の関数のデータサイズを気にせず、全体的なルールを定義するだけで最適化が可能になる。
  • DB の肥大化を自動的に防げる。
  • 責務の分離により、モジュールの保守性が向上する。
• ネガティブ:
  • シリアライズ後のデータサイズを見てから判定するため、メモリ上に全データを一時的に展開する必要がある。
  • Spot クラスのコンストラクタ引数が増え、旧引数（blob_warning_threshold 等）との互換性管理が必要になる。

リミッターの依存性の注入

コンテキストと課題

以前、core.py の Spot クラスは TokenBucket 実装と密結合していました。Spot は tpm (tokens per minute) 整数引数を受け取り、内部で TokenBucket をインスタンス化していました。

この設計にはいくつかの制限がありました： 1. Testing: ユニットテストが TokenBucket 内の本物の time.sleep 呼び出しに依存するため、実行が遅くなっていました。 2. Extensibility: ユーザーがカスタムレートリミッター（例：Redisベースの分散リミッター）や異なるアルゴリズムを提供できませんでした。 3. Separation of Concerns: core.Spot がリミッターのライフサイクルと設定を管理しており、単一責任の原則に違反していました。

判断基準

• Testability: テスト中にスリープ時間を排除するために、MockLimiter や NoOpLimiter を注入できるようにすること。
• Flexibility: コアロジックを修正することなく、ユーザーがカスタムリミッターを実装できるようにすること。
• Clean Core: core.Spot を簡素化し、リミッターの初期化処理を排除すること。

検討した選択肢

• Option 1: 引き続き Spot クラス内でリミッターの実装をハードコードする。
• Option 2: 抽象プロトコル LimiterProtocol を導入し、依存性注入 (DI) を使用してリミッターを外部から提供する。

決定事項

採用した選択肢: Option 2.

レートリミッターを core.Spot から切り離し、依存性注入 (DI) を使用します。

1. Protocol Definition: beautyspot.limiter に consume(cost: int) と consume_async(cost: int) メソッドを規定する LimiterProtocol を定義します。
2. Explicit Inheritance: デフォルトの TokenBucket 実装は、型安全性と明確さのために LimiterProtocol を明示的に継承します。
3. Injection: core.Spot.__init__ を、tpm の代わりに limiter: LimiterProtocol インスタンスを受け取るように変更します。
4. Factory Responsibility: __init__.py の Spot ファクトリ関数が、カスタムリミッターが提供されない場合のデフォルトの TokenBucket 作成を担当します。

影響・結果

• ポジティブ:
  • テスト容易性: MockLimiter などを注入することで、テストの高速化が可能になった。
  • 柔軟性: 外部ストアを利用したリミッターなどを、コアを汚さずに実装可能になった。
  • クリーンなコア: Spot クラスの責務が削減され、コードが簡素化された。
• ネガティブ:
  • 内部クラス _Spot のシグネチャが変更されるため、直接インスタンス化していたコードに影響がある（公開されている Spot ファクトリ経由であれば影響なし）。

宣言的ライフサイクルポリシー

コンテキストと課題

機械学習や生成AIの実験プロセスにおいて、生成されるデータの重要度は均一ではありません。数ヶ月保持すべき「最終モデル」もあれば、数時間で不要になる「一時的なデバッグ出力」もあります。

現在、これらの古いデータを削除するには、ユーザーが MaintenanceService.prune(older_than=...) を呼び出すスクリプトを自作し、定期実行する必要があります。これはユーザーにとって負担であり、設定を忘れるとディスク容量を圧迫する原因となります。また、beautyspot は常駐プロセスを持たないため、クリーンアップのトリガー設計が課題となります。

判断基準

• Cognitive Load Reduction: ユーザーが「Toil（苦役）」から解放され、データの寿命を宣言するだけで管理が完結すること。
• Predictable Performance: 有効期限の判定や削除処理が、メインの実行パスのレイテンシに悪影響を与えないこと。
• Safety: デフォルトではデータを無期限に保持し、意図しないデータ消失を防ぐこと。

検討した選択肢

• Option 1: 命令的なアプローチ。ユーザーが必要に応じて削除スクリプトを記述・実行する。
• Option 2: 宣言的な retention パラメータとデータベースでの有効期限管理を導入し、アクセス時のチェック（Lazy Expiration）と CLI による一括削除を組み合わせる。

決定事項

採用した選択肢: Option 2.

ユーザーが「データの寿命（What）」を宣言するだけで済むよう、以下の仕組みを導入します。

1. retention Parameter for @mark

デコレータおよび run メソッドに retention 引数を追加します（例: "7d", "1h", None）。

2. Database Schema Change (expires_at)

タスク作成時に寿命を計算し、tasks テーブルの expires_at カラムに保存します。

3. Lazy Expiration (Access-time Check)

キャッシュ取得時（spot.db.get）に、expires_at < current_time であれば「キャッシュミス」とみなして None を返します。この時点では物理削除は行わず、レイテンシへの影響を最小限にします。

4. Explicit Garbage Collection (CLI)

期限切れデータの物理削除は、CLI コマンド $ beautyspot gc --expired によって一括で行います。

影響・結果

• ポジティブ:
  • 認知負荷の低減: 関数定義時に寿命を決めるだけで、後片付けを気にする必要がなくなる。
  • パフォーマンス: 有効期限の判定は TIMESTAMP 比較のみで高速。
  • 安全性: デフォルトは無期限であるため、安全。
• ネガティブ:
  • 容量解放の遅延: CLI コマンドが実行されるまで、期限切れデータもディスクに残り続ける。
  • マイグレーション: 既存テーブルへのカラム追加が必要。