# Geduldh の文書保存契約 2026-11-01、ローカルDocument Storeと一時展開の初期分離を実装。 GeduldhはSHA-256で識別する不変の文書バイト列を保存・取得・検証する。 従来の `internal/documentstore` の実装を移し、保存形式、DBスキーマ、公開URLは変えない。 名称の位置付けは [コンポーネント命名と責務](component-names.md)、 外部ストレージと運用の計画は [保存基盤の多様化](../storage-portability-and-operations.md) を参照。 ## 実装と責務 | 層 | 所有するもの | 所有しないもの | | --- | --- | --- | | `internal/geduldh` | Store契約、ローカルpayload、保存キー、サイズ・hash検証、容量制限付き一時展開 | SQL、認証・認可、Page/Revision、GCの削除判断 | | `internal/documentstore` | 旧公開型のalias、旧コンストラクター・Keyの委譲 | 独自の保存実装・検証ロジック | | `internal/store` | Revisionと参照のtransaction、DB-only互換、バックフィルのidentity・checkpoint、read-only運用 | 別実装のローカルpayload writer | | server / DR / CLI | 認可後の配信、外部ツール、保全・復元の手順 | hashを知っていることによる認可の省略 | アプリケーションと旧入口からGeduldhへの一方向依存とする。Geduldhからstore、DB、 server、旧documentstoreへ戻る参照は作らない。HTTPレスポンスや権限判定も持たせない。 `Component = "geduldh"` は内部の固定識別名であり、保存ディレクトリやサービス名ではない。 ## 保存と取得の契約 `geduldh.Store` は既存の `documentstore.Store` と同じ型として扱える。 | 操作 | 契約 | | --- | --- | | `Stat(ctx, hash)` | 正規化したhashとバイト数を返す。内容全体の検証ではない | | `Open(ctx, hash)` | `Read`、`ReadAt`、`Seek`、`Close` に対応するReaderを返す。全体を先読みしない | | `PutIfAbsent(ctx, hash, size, reader)` | サイズとSHA-256を検証し、完全なpayloadだけを上書きせず公開する | | `Verify(ctx, hash)` | ストリーム全体を読み、SHA-256の一致を検証する | 通常の `Open` / `Stat` は全体をhash検証しない。Range配信やZIPの部分読み取りで ファイル全体の走査を強制しないためである。検証が必要な経路は `Verify` または検証付き Materializerを選ぶ。既存のRevision本文取得時のhash検査はstore側に残る。 保存キーは `sha256//<64桁hash>`、ルートは既存の `documents`。 hashの前後空白の除去・小文字化、既存エラーの同一性を維持する。Path、ファイル名、 Domain、言語、Revision UUIDは保存キーに混ぜない。配置の変更で公開URLやETagを変えない。 ローカル保存はルート内アクセス、64 KiB単位の検証コピー、一時ファイル、ファイルfsync、 hardlinkによるno-replace公開、ディレクトリfsyncを維持する。 既存payloadは再検証し、破損していても入力で上書き修復しない。 `NewLocal` は保存先を作成しない。ルートの準備とバックフィルは起動・運用側の責務とする。 書込みではpayloadの永続化を先に完了し、その参照を持つRevisionのDB transactionを 後で確定する。DB側の競合・rollbackで未参照payloadが残ることは許容する。 Geduldhは参照数を判断せず、`Store` にDeleteを設けない。GCは保持・参照・backup pinを 判断する別の経路とし、今回の分離では変更しない。 ## 外部ツール用の一時コピー `Materializer.Acquire` は同じhashの取得を共有し、検証済みのノードローカルコピーを `Lease` で返す。ここでのleaseは一時ファイルの利用権であり、分散ジョブの期限付きリースではない。 最後の利用者がCloseするとコピーを削除する。正本のhardlinkを外部ツールへ渡さない。 一人の待機中断で他の利用者を巻き込まず、全員が中断した場合は取得を取り消す。 既存アプリケーションの上限を維持する:同時取得2件、待機・利用中を含め64件、 予約容量合計2 GiB、共有取得期限2分。呼出し側のファイル単位上限とcontextも適用する。 一時ディレクトリは0700、コピーは0400。削除失敗時には予約容量を解放済みと扱わない。 これらはアクセス元アプリケーションの設定であり、外部ストレージ対応の宣言ではない。 ## 互換性と今回の変更範囲 - 旧documentstoreの型・エラーはalias、関数はGeduldhへの委譲とし、実装を二重に持たない。 - storeの保存、読み取り、サイズ・部分取得、一時展開はGeduldhへ接続する。 - `.document-store-id`、バックフィルのUUID cursor、DB-only互換、起動時移行は変更しない。 - DR manifest、スナップショットの構造、復元手順、保存済みデータは変更しない。 - UI、URI、設定キー、イメージ名、イベント型、consumer checkpointは変更しない。 これは既存の保存実装の分離であり、新たなファイル移行・DB migrationを必要としない。 任意のmount先での永続性、外部backend、マルチノードHAを追加するものではない。 ## 残件 - [ ] S3 / SFTPなどのbackendを、条件付き作成・部分取得・破損・切断の共通契約試験を経て追加する。 - [ ] NFS / SMB / SSHFSはno-replace公開・fsync・mount喪失の実環境試験を行う。ローカルパスであるだけで対応済みとしない。 - [ ] 旧Revision保存・本文取得を含む全経路へcontextを伝播する。 - [ ] payload、可変正本、秘密情報、scratchの配置設定を分離する。 - [ ] 一時展開の上限を設定化し、削除失敗・クラッシュ残骸の安全な回収とメトリクスを追加する。 - [ ] Documentのサイズをメタデータ化し、外部backend導入時の一覧のStat/HEAD多発を防ぐ。 - [ ] GCの参照snapshot・保持・backup pinと、外部ストレージの削除契約を整備する。 ## 検証 合成payloadと一時DB・ディレクトリで、次を検証する。 - 移動前レイアウトの読み取り、新旧入口の型・エラー・キー互換、既存inodeの保持。 - 並行書込み、不完全入力・既存破損の拒否、キャンセル、ルート外へのsymlink逸脱防止。 - Range / ReaderAtと逐次読み取りの独立性、ZIP配信、認可を伴う不変オブジェクト配信。 - 一時コピーの共有、容量・件数・時間制限、最終Closeでの削除、正本からの分離。 - 永続化失敗時のRevision非確定、metadata競合時の正本保全、バックフィルの再開。 - Geduldhで保存 → 既存DR snapshot → verify → restore → Geduldhで検証・読取り。 実行結果は [コンポーネントの検証記録](component-names.md#検証記録) に記載する。 本番データの操作、commit・push・本番展開はこの初期分離には含めない。