🛡 壊れたデータを3種類に分けたら復旧設計が一気に決まった話

ローカルにデータを持つアプリを書いていると、いつか「壊れたデータを読み込んでしまったとき、どうするか」を決めなければいけません。この記事は、その判定を最初「壊れているか / いないか」の真偽値で扱おうとして詰まり、破損を3種類に分解した途端に残りの設計が芋づる式に決まったという記録です。データベースの列設計から通知の強さまで、判定の粒度ひとつで決まる範囲の広さが今回の主題です。

筆者は「Trueful」という開発者向けのOSSブラウザを個人で作っています。Truefulの中心にあるWorkspaceは、タブ・セッション・セキュリティ設定をひとまとめにした作業単位で、実体はJSONのマニフェストです。#0007でWorkspaceの作成・再アクティブ化フローを設計したので、今回はその手前に置く「壊れたマニフェストの扱い」を詰めました¹。

「破損チェック」をひとまとめに考えていた

最初に書いた処理の見出しは「破損確認」の一語でした。返り値は真偽値。壊れていたら何らかの復旧を試みる、というつもりでした。

ここで手が止まりました。「何らかの復旧」が書けないのです。書こうとすると、想定している壊れ方によって手順がまったく違うことに気づきます。JSONのパースに失敗するケースと、JSONは読めるが項目が足りないケースと、マニフェストが参照しているファイルが実在しないケース。この3つは、検知の方法も、復旧できるかどうかも、ユーザーに何を伝えるべきかも別物でした。

検討した候補

「壊れたWorkspaceをどう扱うか」について、3つの案を比べました。

候補	判定
破損の種類ごとに検知と対処を分ける	採用
破損を真偽値で扱い、壊れていたら一律に復元を試みる	却下
壊れていたら開かせず、ユーザーに作り直させる	却下

「破損 = 真偽値」を却下した理由

真偽値にすると、呼び出し側が何もできません。

破損確認を呼ぶのは、起動時のクリーンアップ処理と、Workspaceの再アクティブ化フローの2箇所です。どちらも「壊れている」と言われた後に、自分で復元を試みるのか / ユーザーに知らせるのか / 黙って飛ばすのか を決める必要があります。真偽値しか返ってこないと、その判断材料が呼び出し側に届きません。

結果として、判断ロジックを破損確認の内側に押し込むことになります。すると転換の起きた #0007 と同じ問題——1つの処理が「何をする処理か」を一文で説明できなくなる——が再発します。

最終的に、破損確認は該当するパターンそのものを返す設計にしました。判断は呼び出し側の責任として残します。

「壊れていたら作り直させる」を却下した理由

実装はいちばん簡単です。壊れたものは開かせない、以上。

ただ、Truefulの思想編（#0001）ではLayer 2の原則として Failure Friendly——失敗を前提に、復旧しやすい設計にしておく——を掲げています。書き込み中にクラッシュしただけのWorkspaceを、作り直しでしか救えない設計にするのは、この原則に真正面から反します。

再検討する条件はあります。復旧機構の実装・保守コストが、Workspaceを作り直すコストを明らかに上回るようなら、この案に戻る余地はあります。ただ現時点で、Workspaceはタブ構成・セッション・セキュリティ設定を含む「作業環境そのもの」なので、作り直しのコストはかなり高い。今回は却下しました。

3パターンに分解して、対処を分けた

採用案の中身です。

#	破損の内容	典型的な原因	アプリ側で復元できるか
①	マニフェストJSON自体が壊れている	書き込み中のクラッシュ	○ バックアップから復元可能
②	JSONは読めるが必須項目が欠けている	作成フローが途中で中断	△ 作成フローの続きへ誘導
③	参照先ファイルが実在しない	ユーザーが手動で削除した等	✕ アプリの外で起きたこと

分解して初めて見えたのは、①と③のあいだにアプリの権限境界が走っていることでした。①はアプリが自分で書き込んだデータの不整合なので、自分で直せます。③はファイルシステム上でアプリの知らないうちに起きた変化なので、アプリ側にできることは原理的にありません。同じ「壊れている」でも、責任の所在が違います。

この3つに当てはまらないケースとして「Workspace ID自体が破損している」場合も検討しました。この場合、どのバックアップと紐付けるべきかという対応関係そのものが成立しないので、3パターンには含めず「識別不能・復旧不可」として別扱いにしています。

バックアップ自体が壊れる可能性

「①はバックアップから復元する」と決めたところで、当然の疑問が出ました。バックアップ自体が壊れていたら？

これは実際その通りで、バックアップも結局は「書き込み」である以上、①とまったく同じ破損リスクを抱えます。バックアップを置いただけでは、壊れる場所が1つ増えただけです。

そこで、バックアップを保存するときに SHA256 のチェックサム（データの指紋のようなもの）も一緒に記録し、復元時にバックアップ自体の正しさを検証できるようにしました。バックアップの更新はマニフェストが変更されるたびに毎回行います。バックアップが最新を反映していないと、いざというときに古い状態へ巻き戻ってしまうためです。

バックアップを別テーブルに分けた理由

保存先も検討しました。

候補	判定
`workspace` とは別テーブルに保存	採用
`workspace` テーブルに列を追加	却下

マニフェストJSONはタブ構成を含むためサイズが大きくなりがちです。Workspaceの一覧表示のように頻繁に走るクエリが読むテーブルに混ぜると、普段の動作までその重さを引きずります。バックアップは「めったに読まないが必ず必要」なデータなので、アクセス頻度が違うものは物理的に分ける、という判断です。

「独立させる」と「呼び忘れを防ぐ」は両立できる

設計中、こういう悩みに突き当たりました。バックアップ処理は独立した部品にしたい。でも独立させると、マニフェストを保存する側が呼び忘れる余地が生まれる。

しばらく二択だと思っていたのですが、対立していませんでした。

バックアップ処理は独立した部品として作る（単体でも呼べる）
マニフェスト保存処理の内部からその部品を呼ぶ（保存とバックアップが自動的にセットになる）

外から見れば「保存すれば必ずバックアップされる」、中を見れば「バックアップは独立した部品」。#0007で services / flows に分けたときと同じパターンが、別の場面でそのまま効きました。設計パターンが2回目に出てくると、1回目より速く気づけます。

SQLiteの列設計：1列にまとめかけた罠

Workspaceの状態を永続化する列も、この機会に確定させました。当初は「最終アクセス時刻」を1列で表すつもりでしたが、これが罠でした。

LRU判定に使う「最後に開いた時刻」
Archive判定に使う「非アクティブになった時刻」

この2つは意味が違います。「開いてすぐ閉じた」場合と「開きっぱなしで長く使った」場合で、両者は大きくズレます。1列にまとめていたら、どちらかの判定が静かに不正確になっていました。

最終的な列設計です。

列名	型	デフォルト値	役割
`status`	TEXT（`active` / `dormant`）	`active`	Workspaceの現在の状態
`last_used_time_ms`	INTEGER	作成時刻	最後に開いた時刻。LRU判定に使用
`dormanted_time_ms`	INTEGER（NULL許容）	`NULL`	非アクティブになった時刻。Archive判定に使用

dormanted_time_ms のデフォルトを NULL にしたのもポイントです。「まだ一度もDormantになっていない」を 0 で表すと、「1970年1月1日にDormantになった」という嘘のデータになります。存在しないことは NULL で正直に表現する。基本ですが、経過日数を計算する側の実装を考えて初めて実感が伴いました。

列名はSQLの慣習に従ってスネークケースにしています。Renderer層で使うキャメルケースとの変換境界も、この段階で意識的に分けました。

Archive状態をデータベースに持たないと決めた

status に archived が無いことに気づいた方がいるかもしれません。ここも当初案から変えた部分です。

最初は「ArchiveはDormantとは別の状態」として設計するつもりでした。ところが内部処理を書き出してみると、Dormantとまったく同じなのです。違うのは表示だけ。

そこまで来ると、DBの状態列に archived という値を持たせる必要すらないという結論になります。「dormantになってからの経過日数」を表示のたびに計算すれば済むので、「状態を書き換える処理」自体が不要になる。書き換え処理が存在しないなら、書き換え忘れやタイミングのズレというバグの余地も、最初から存在しません。既存のLRUや再アクティブ化フローも、Dormant / Archive を区別せずそのまま使い回せます。

判定の境界となる日数はハードコードせず、定数として一元管理する方針にしました。将来この値を調整したくなったときに、複数箇所を探し回らずに済むようにするためです。

通知の強さは「深刻度」ではなく「取れる行動」で決める

最後に、3パターンをユーザーにどう伝えるかです。

パターン	通知の強さ	理由
①（自動復元済み）	トースト通知のみ	ユーザーの対応が不要
②（未完成）	作成フローの続きへ誘導するポップ	「続きをやれば直る」という前向きな行動につながる
③（復旧不可）	確認ダイアログ	アプリ側で解決できず、ユーザーの判断が必須

深刻さの順に強くしたのではありません。ユーザーがそれを見て何ができるかで強さを決めています。②は深刻さで言えば③より軽いですが、行動につながるぶん、トーストより一段強い表示に値します。逆に①は、内部で起きたことは深刻でも、ユーザーにできることが無いのでトーストで足ります。

この基準も #0002 のDesign Systemで整理した「割り込みコストのはしご」の応用です。

再検討条件と、まだ決まっていないこと

ADRを書き終えた時点でも、意図的に残した論点があります。

バックアップの世代管理方針（最新1件のみ保持 / 複数世代保持）
チェックサム検証のタイミング（復元前に検証するか、復元後に検証するか）
破損確認と、起動時クリーンアップ・再アクティブ化フローとの具体的な組み込み順序

加えて、今回の決定を将来見直す条件も書き残しました。Archive判定を都度計算にした以上、Workspace数が増えたときの計算コストが問題になるなら、キャッシュか列の再導入を検討する。また起動時クリーンアップは、判定条件を持たない「毎回無条件で実行」を選びました。異常終了かどうかを判定する方式は起動が速くなりますが、判定を間違えると本来動くべきときに動かないリスクがあります。実装初期の今はシンプルな方を取る、という判断です。ただしこれを選んだ以上、「毎回実行しても起動体験を損なわない軽さを保つ」という制約も同時に背負いました。

1つのADRで全部を決めきろうとせず、決まったところまでを確定させて次に送る。これもLayer 0の Time First の実践だと捉えています。

総括

この日いちばん効いたのは、SHA256でもテーブル分割でもなく、「破損」という一語を3つに割ったことでした。

判定の粒度を上げただけで、返り値の型が決まり、呼び出し側の責務が決まり、通知の強さの基準が決まり、どこまでがアプリの責任範囲かの線が引けました。逆に言えば、真偽値のまま進んでいたら、これらは全部「実装しながら考える」に先送りされていたはずです。

抽象度の高い言葉でひとまとめにしている限り、その下にある判断は見えません。設計が進まないと感じたときは、たいてい言葉を1段細かくすると進む——今回の1日で得たのは、その一点です。

次回

#0009では、ここで残した宿題（バックアップの世代管理、チェックサム検証のタイミング）を詰めたうえで、services/ flows/ 配下への実装に着手します。着手順はLRUや作成フローからではなく、破損検知ロジックからの予定です。他のすべての処理がこの判定結果に依存する、依存関係の起点だからです。

GitHub

今回の決定の詳細（ADR-012、データスキーマ）はこちら。

Workspaceのライフサイクルと状態遷移の仕様は MVPスコープにあります。

AIの利用について

この記事は、Claudeに一次稿を作成してもらい、内容を確認・修正したものです。設計判断そのものは自分で行っており、上記の却下理由やトレードオフもClaude相手の壁打ちの中で自分が詰めたものです。Claudeの使い方については番外編1に詳しく書いています。

この日は前半に、GitHubのWeb UIから直接コミットしていたぶんとローカルの未コミット変更が食い違って divergent branches が出る、というGit整理もやっています。merge運用に決めてリポジトリ単位で設定しただけなので、本記事では割愛します。 ↩