非可逆な正規化(slugify等)をキーにした保存は、キー一致で同一性を判定しない — 本文に原文を保存し読み出し時に完全一致照合する
設計判断
キャッシュ
知識
判断
キャッシュ・成果物ファイル・レポートなどを「正規化したキー(slugify、空白→ハイフン、記号除去、長さ切り詰め等)」で保存するとき、その正規化が非可逆なら別の入力が同じキーに潰れる(例: 「ai agent」と「ai-agent」、記号を含む語と含まない語、先頭 N 文字が同じ長い語)。キーの一致だけで「同じ対象のデータ」と判定すると、別対象の結果を黙って返す取り違えが起きる。下流が追記専用の台帳や課金処理なら、汚染は静かに永続化する。
実装規則
- 保存時: 本文(ペイロード)に正規化前の原文キー(と同一性に関与する全次元。例: 検索語と市場・ロケール)をそのまま保存する
- 読み出し時: ファイル名一致は「候補の発見」にのみ使い、本文の原文キーが要求値と完全一致するかを照合してから使う。不一致は「キャッシュ不在」と同じ扱い(fail-soft なら再取得へフォールバック)
- テスト: 正規化で同一キーに潰れるペア(空白/ハイフン差・記号有無)を意図的に作り、互いにヒットしないことを固定する。次元の片方だけ変えたケース(同じ語・別ロケール)も別ケースで固定する
なぜキー側の工夫では解決しないか
- エスケープを可逆にする選択肢もあるが、ファイル名には長さ上限・使用不可文字があり、完全に可逆なキーは可読性と衝突する。「見やすいキー+本文照合」の二段構えが実用上の落としどころ
- 関連原則: 別コンポーネントが後で照合する ID は照合側の正準形に合わせる(書き込み時正規化)。本件はその逆方向の補題 — 正規化が情報を捨てる場合は、正規化形を同一性の根拠に格上げしない