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

コンポーネント構成

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 等の定数により、グローバルポリシーの個別上書きに対応

インターフェース

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日）

エッジケース

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

インターフェース

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 (無限大の秒数) を提供し、ポリシーに関わらず永続化を指示できる。

目的

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", "" 等）も拒否されること

実装概要

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 を返すようオーバーライドされている

Declarative Lifecycle Policy

Context and Problem Statement / コンテキスト

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

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

Decision Drivers / 要求

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

Considered Options / 検討

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

Decision Outcome / 決定

Chosen option: 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 によって一括で行います。

Consequences / 決定

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

Probabilistic Auto-Eviction for Storage Maintenance

Context and Problem Statement / コンテキスト

beautyspot はキャッシュの TTL をサポートしており、期限切れデータは論理的に無効化されます。しかし、ユーザーが明示的にクリーンアップを呼び出さない限り、有効期限切れのメタデータや巨大な孤立 Blob ファイルは物理的に削除されず、ストレージが肥大化し続けるという問題がありました。

ユーザーにインフラ管理を意識させない「黒子」としての哲学を維持しつつ、自動でガベージコレクション（エビクション）を行う仕組みが必要になりました。

Decision Drivers / 要求

• Autonomy: ユーザーが手動でメンテナンススクリプトを書くことなく、ストレージの肥大化が自動的に抑制されること。
• Zero Latency Impact: エビクション処理がアプリケーションのメインロジックの応答速度（レイテンシ）を低下させないこと。
• Simplicity: 複雑な容量計算や頻繁な DB 更新を避け、実装と保守のコストを最小限に抑えること。

Considered Options / 検討

1. Capacity-based LRU (Least Recently Used) Policy:
   • ストレージ容量やレコード数の上限に達した際に古いデータを削除する。
   • 評価: 却下。キャッシュヒットのたびにタイムスタンプを更新する必要があり、DB の書き込み競合やレイテンシ低下を招く。
2. Load-Adaptive Background Eviction:
   • アイドル状態のときにのみクリーンアップタスクを投入する。
   • 評価: 却下。実装が複雑になりすぎる（オーバーエンジニアリング）。
3. Probabilistic Auto-Eviction (確率的自動実行):
   • 新しい結果の保存直後、設定された確率に基づいてバックグラウンドでクリーンアップタスクを投入する。
   • 評価: 採用。 シンプルかつ低コスト。

Decision Outcome / 決定

Chosen option: Option 3.

確率的自動エビクションを採用します。

• Spot の初期化パラメータに eviction_rate: float = 0.0 を追加し、オプトイン方式とします。
• エビクション処理は、メインスレッドやイベントループをブロックしないよう、_BackgroundLoop にオフロードします。
• ロック競合を防ぐため、掃除タスクの内部に非ブロッキングロックを導入し、重複実行を安全にスキップさせます。

Consequences / 決定

• Positive:
  • ユーザーは設定一つで、メインロジックの性能を犠牲にすることなくストレージの肥大化を防げる。
  • 実装がシンプルで保守コストが低い。
• Negative:
  • 確率に依存するため、決定論的な容量解放の保証はない。厳密な管理が必要な場合は引き続き手動での呼び出しが必要。