Files
pages/docs/design/storage-portability-and-operations.md
T
2026-11-15 05:47:14 +09:00

1228 lines
108 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 保存基盤の多様化と運用機能の統合
状態:詳細設計・段階導入。2026-11-15 更新。
本書は [基本設計](arch.md) と [拡張契約](platform-extension-architecture.md) を補完する。
各 TODO は実装済みを意味しない。本番 DB・保存先の移行は別途承認する。
## 1. 優先順位と対象
先に SQLite / PostgreSQL / MySQL、Redis 等の KV、ローカル / S3 / SSH / NFS / SMB の
役割・契約を整える。その上にバックアップ、リリース、CLI、export/import、Web バックアップ、
初回「ようこそ」画面を載せる。Web と CLI で別の保存実装を作らない。
実装順は **保存契約 → 正本の分離 → DB 移植 → 外部 Document → 運用ジョブ → UI**。
Redis を RDB の代わりに選ぶ UI や、S3 URL をローカルディレクトリ欄へ指定する方式は採用しない。
初期設定が SQLite + ローカルだけでも、単一ノード運用が追加サービスなしで成立すること。
## 2. 現行実装の監査
| 箇所 | 現状 | 移植前に必要な変更 |
| --- | --- | --- |
| `internal/db/db.go` | SQLite 固定、WAL、busy_timeout、NORMAL | 接続プロファイル、durability 設定、driver ごとの検証 |
| `internal/db/migrate.go` / `Ensure*Schema` | DDL とデータ移行が分散。core bootstrap の ALTER エラー無視は是正、他の Ensure は継続監査 | 新 migration runner への段階集約と driver 別 DDL |
| `internal/store` | `*sql.DB` への直接 SQL。SQLite 固有式が多い | repository ごとの SQL 分離・契約テスト |
| `internal/store/document_store.go` | SHA-256 正本と DB body の移行互換 | payload backend の分離、復旧時以外の暗黙再作成の縮小 |
| `internal/calendar/repository.go` | 月別 ICS + calendar.json、flock、rename、DB はキャッシュ | mutable canonical repository と条件付き世代更新 |
| `DocumentRoot` の利用箇所 | calendar、auth.key の親、preview、import、payload を兼用 | payload / canonical state / secrets / scratch の分離 |
| `DocumentPath` の利用箇所 | 外部コマンドへ直接ローカルパス | 期限付き Materialize、容量制限・後処理 |
| `data/pageswiki-cli` | Python sqlite3 とローカル Document を直接操作 | online API モードを主経路に、offline repair を明示分離 |
調査時点で SQLite 固有語(PRAGMA、sqlite_master、rowid、INSERT OR、strftime 等)が
テストを除く約 50 ファイルに存在する。接続ドライバだけ追加しても動作しない。
「接続できた」と「PagesWiki の全機能を利用できる」をサポート状態として区別する。
## 3. 正本・派生物・機密情報を分離する
| 層 | 主なデータ | 保存先 | 消失時の扱い |
| --- | --- | --- | --- |
| MetadataRepository | UUID、Path、Revision、ACL、ユーザー/グループ、タスク、設定、outbox、確定ジョブ | SQLite / PostgreSQL / MySQL | バックアップから復元が必要 |
| DocumentStore | SHA-256 で識別する不変バイト列 | local / S3 / 検証済み mounted filesystem / SFTP | バックアップから復元が必要 |
| CanonicalStateRepository | カレンダーのメタ情報、月ごとの ICS 世代、ユーザー設定 | 世代付きファイル正本(local から段階拡張) | バックアップから復元が必要 |
| CacheStore | 検索・表示・サジェスト・リソース集計の再生成可能データ | memory / SQL cache / Redis | 正本から再生成 |
| SecretStore | auth.key、署名鍵、暗号化鍵、接続資格情報 | secret file / 環境 / 外部 Secret manager | 別権限・暗号化して保全 |
| Scratch/Materialization | import 展開、外部ビューア用一時ファイル、生成中 preview | ノードローカルの専用領域 | 破棄して再実行 |
セッション失効、承認、ジョブ完了、タスクの変更を Redis のみの情報にしない。
「Redis の AOF を有効にしたから正本のバックアップを省略できる」とはしない。
## 4. 共通インターフェース
### 4.1 不変 Document
Go 契約は `internal/geduldh.Store`。2026-11-01に既存ローカル実装を
[Geduldh](ja/geduldh.md) へ分離し、`internal/documentstore.Store` は同じ型の互換aliasとした。
```text
Stat(ctx, sha256) -> { hash, size }
Open(ctx, sha256) -> Reader + ReaderAt + Seeker + Closer
PutIfAbsent(ctx, sha256, size, stream)
Verify(ctx, sha256)
```
- 保存キーは既存互換の `sha256/<先頭2文字>/<64桁hash>`。Path やファイル名ではない。
- サイズとハッシュの検証前に、完全な Document として読める状態にしない。
- 不変 payload を先に永続化し、その後に参照する DB transaction を commit する。
- DB rollback で未参照 blob が残るのは許容するが、存在しない blob の参照確定はしない。
- 読み取りの Open/Seek/ReadAt は大容量全体の先読みをしない。remote range は上限・期限付き。
- ETag は HTTP の条件付き取得に使い、SHA-256 とは別フィールドとする。
- timeout、not found、破損、認証失敗、容量不足を区別する。エラー時に local へ勝手に書かない。
- 通常の Put/Read インターフェースに Delete を含めない。GC は参照 snapshot、保持、backup pin、
進行中 upload の保護を持つ専用経路から実施する。
- local path を返すことを全 backend の必須機能にしない。
接続済みの範囲はローカルの保存・通常読み取り・サイズ取得・部分読み取りと、
外部ツール用 Materialize。HTTP の主要な本文配信・部分取得には Request.Context を接続した。
remote backend、従来の Revision 本文取得/保存 API 全体への context 伝搬は未接続。
既存の DB body fallback は互換のため維持する。起動時 backfill は保存先ごとの進捗を記録し、
完了済みの保存先では revisions の走査を省略する(後述)。
### 4.2 可変正本
カレンダーはファイル正本を維持し、月ごとの不変 ICS 世代を作成してから
calendar manifest を `CompareAndSwap(expectedVersion, nextManifest)` で更新する。
DB のカレンダー cache は manifest version に従って再生成する。
S3 で POSIX rename/flock を模倣せず、条件付き manifest 更新を使う。
カレンダーの競合は明示的に返し、古いキャッシュで正本を上書きしない。
世代の削除はバックアップ pin と参照中 version を考慮する。
### 4.3 外部ツールへの受け渡し
`Materialize(ctx, hash, quota) -> localPath, cleanup` を別サービスにする。
archive/PDF/動画/PE/DEB 等のローカルパス必須ツールはこれを利用する。
SHA-256 検証、容量上限、同一 blob の取得集約、参照中の退避禁止、期限、キャンセルを持つ。
remote Object URL や presigned URL を無条件にツールへ渡さない。
ZIP の範囲参照で足りる処理は Materialize せず ReaderAt を使う。
実装は `internal/geduldh.Materializer`(旧 `internal/documentstore.Materializer` は互換alias)と
`Store.MaterializeDocument(ctx, hash, maxBytes)`。同じ Store 内で同じ hash の取得をまとめ、
利用者ごとの lease で参照中のコピーを保持する。待機者の一人がキャンセルしても他の待機者の
取得は中断しない。全員がキャンセルしたら共有取得を中断し、最後の lease の Close で削除する。
取得・検証に成功するまで外部コマンドへパスを渡さない。コピーは 0700 の専用一時ディレクトリに
0400 で作り、正本への hardlink は渡さない(外部ツールが誤って正本を変更するのを防ぐ)。
現時点の固定上限(将来 deployment profile に移す):
- Store ごとに同時取得 2 件、取得待ち/利用中を含め 64 件、予約容量合計 2 GiB。
- 共有取得の期限は 2 分。呼び出し元の request/preview/metadata の期限でも待機を中断する。
- metadata / PDF は 512 MiB、動画 / 非 ZIP 展開は 1 GiB、Excalidraw は 16 MiB。
- 保存先は `TMPDIR`(未設定時は OS の一時領域)。DocumentRoot やネットワークマウントを使わず、
ノードローカルの十分な空き容量を持つ領域を指定する。tmpfs の場合はメモリ消費になる。
- 削除失敗時には予約容量を解放済みと見なさない。プロセス強制終了で残った一時ファイルの
安全な回収とリソース監視へのメトリクス接続は残件。
画像・ZIP サムネイル、ZIP 内の個別ファイル配信は Reader/ReaderAt を直接利用する。
ZIP の個別配信は互換 DB body の全体 hydration をしない。非 ZIP / PDF / 動画などは、
ローカル正本でも検証付き一時コピーを作るため追加 I/O が発生する。永続キャッシュや
reflink 最適化は容量/失効/破損検出の契約を保った上で別途導入する。
## 5. RDB の対応設計
### 接続と migration
- 接続プロファイルはインスタンス管理で指定。Domain 管理者に DSN を公開しない。
- driver ごとに host/port/database/TLS/secret reference/pool/timeout を持つ。
- 未対応 driver は起動前に明示エラー。SQLite にフォールバックしない。
- SQLite を既存互換で維持し、まず PostgreSQL、次いで MySQL 8.4 LTS / InnoDB を対象にする。
PostgreSQL の最低対応版は CI matrix の確定時に明示する。MariaDB を MySQL と同一扱いしない。
- 起動時 Ping、schema version、driver と schema の一致を検証する。
- migration は driver/version/checksum/applied_at の履歴と排他的ロックを持つ。
起動ごとの分散 Ensure* を段階的に集約し、未知の DDL エラーを無視しない。
- MySQL の DDL は暗黙 commit を前提に、再開可能な移行段階を記録する。
migration rollback を DB transaction だけで保証しない。
#### 初段の migration runner(実装済み範囲)
`internal/db.ApplySQLiteMigrations` は component ごとに連続した version、name、SQL の
SHA-256 checksum、適用時刻を `schema_migration_steps` に記録する。
専用 DB connection の `BEGIN IMMEDIATE` で他プロセスとの適用を直列化し、
DDL と履歴を一つの transaction で commit する。失敗時は rollback し、transaction の
状態が確定できなかった connection を pool へ戻さない。
適用済み SQL の変更、version の欠落、バイナリより新しい移行履歴は起動時にエラーにする。
適用済みの手順は編集せず、新しい version を追加する。
移行済みの利用先は Document backfill の進捗テーブルと、下表の 6 領域。
既存の `schema_migrations` / `revision_metadata_v1` は変更せず維持する。
core bootstrap の列追加は PRAGMA で存在確認し、未知の ALTER エラーを無視しない。
古い revision の hash 計算は 128 件ずつ UUID を選択し、本文は一度に一件だけ読み込む。
既存のすべての Ensure*Schema が新 runner へ移行したわけではなく、
PostgreSQL/MySQL 対応や schema drift の完全な検査を意味しない。
| component | 対象 | 旧版から不足時に追加する列 |
| --- | --- | --- |
| `projection-metadata` | `projection_metadata` | なし |
| `resource-history` | `resource_samples` | なし |
| `broadcasts` | `broadcasts` | なし |
| `browser-navigation` | `browser_navigation_links` | `is_directory` |
| `adapter-sessions` | `adapter_sessions` | `root_path`, `principal_uuid` |
| `imports` | import session/item/journal/City 対応の 5 テーブル | `import_journal.completed` |
| `event-jobs` | jobs/definitions/logs/log policies/log buckets/queue settings | `event_uuid`, `priority`, `max_attempts`, `started_at_ms`, `finished_at_ms`, `cancel_requested` |
| `document-store` | 本文移行の進捗 `document_backfills` | なし(v2 で契約を検証) |
定義は `internal/store/schema_modules.go` / `schema_jobs.go` と
`document_backfill.go` に置き、診断時には同じ定義を参照する。既存 `Ensure*Schema` メソッドは
互換ラッパーとして残し、テーブルの再作成・行の削除はしない。
条件付き列追加は存在確認と ALTER を同じ migration transaction 内で実施する。
追加列の宣言と schema assertion も checksum 対象とする。旧式定義の checksum は、
新しい空フィールドを JSON へ出さないことで維持する。
component の最新 version に、現在のスキーマ全体に必要な assertions を記載する。
適用済みでも毎回検査する。必要な列、一意性の対象列、インデックスの所属と列順、
追加列の型/NOT NULL/default、adapter session の部分 UNIQUE 条件を確認する。
すべての列の型・CHECK・照合順序・外部キーまでを網羅する汎用 diff ではない。
後続 version が意図的に列を削除する場合に備え、過去 version の assertions は最新の契約で
置き換える(過去の定義と checksum は改変しない)。
初回採用時は既存の行を保持したまま不足する既知の列・索引を作成する。
採用後に schema が欠落/変更した場合は自動再作成せず、起動を止めて調査対象とする。
event_jobs 用の検索索引は projection の初期化から Event Jobs の初期化へ移し、
派生キャッシュからジョブ正本のスキーマへ向かう不要な依存を取り除いた。
イベントキューは、既知の不足列を追加する v1 と、列を使う索引・周辺テーブルを採用する v2 に分ける。
実行中ジョブの再キューイングは通常起動の状態復旧処理として分離し、migration runner や診断から呼ばない。
`pageswiki schema status|check` は `mode=ro` / `query_only` 接続で、管理対象の履歴/checksum と
最新 schema assertions を検査する。読み取り transaction の snapshot から判断し、
未作成 DB の初期化・鍵生成・本文移行・ジョブ復旧を実行しない。
`check` の終了コードは current=0 / pending=2 / blocked・unknown・実行エラー=1。
未適用 DDL は実行せず計画だけ表示するため、pending の成功を保証する dry-run ではない。
未移行の従来 schema 処理は診断範囲外として出力し、起動リハーサルを別途要求する。
反映前の確認項目は [保存基盤のスキーマ変更・反映手順](../operations/storage-schema-rollout.md) を参照。
#### 再開可能な Document backfill(実装済み範囲)
- `Store.BackfillDocuments(ctx, batchSize)` が一回最大 128 件の UUID/hash を取得する。
本文は不足 blob の一件分だけ読む。単一の巨大な legacy 本文のメモリ上限は別の課題である。
- 保存先の `.document-store-id` と DB の `document_backfills` を対応させ、
UUID cursor・処理数・完了状態・更新時刻を記録する。UUID cursor は VACUUM で変わらない。
- payload の検証・永続化後にバッチの checkpoint を更新する。失敗時は未完了バッチを再実行する。
保存先単位のファイルロックで二重実行を防ぎ、ロック待ちも context のキャンセルを受け付ける。
- 正本が既にある場合はその SHA-256 を検証し、古い/空の DB body は使わない。
破損した正本は互換キャッシュで上書きせず、明示エラーにする。
- 保存先を空のディレクトリへ差し替えると identity が変わり、以前の完了状態を流用しない。
既存正本が一部欠落した場合の検出は verify/repair の役割であり、通常起動で全件監査しない。
- DB-only の旧 writer/importer を止めた保守状態で実施する。通常の Page 保存は
Document 永続化が先行するため、移行 cursor より前の UUID が増えても不足しない。
- 初回移行は引き続き起動前に完了させる。完了済みの通常起動では revisions を問い合わせない。
非同期化する際は未移行 payload の配信・readiness・保守モードの契約を先に整備する。
- backup/restore は `.document-store-id` も含めて保存先を保全する。これは資格情報ではない。
identity が欠落した旧バックアップは新しい保存先と扱い、再検証・移行する。
### SQL 差異と対策
| 差異 | 対策 |
| --- | --- |
| `?` / `$1` | repository の dialect/query builder で生成。文字列の単純置換はしない |
| PRAGMA / sqlite_master | schema inspector を backend ごとに分離 |
| `rowid` による順序 | 明示 sequence または `(created_at_ms, uuid)` 等の仕様化した順序へ移行 |
| INSERT OR IGNORE/REPLACE / UPSERT | conflict target と更新列を明示。REPLACE の delete+insert を模倣しない |
| 時刻関数 | 保存時刻はアプリ生成 UTC epoch ms / BIGINT、必要な DB 時刻用途は別途定義 |
| LIKE / 照合順序 | Path/UUID/ハッシュの大小文字・正規化規則を共有。DB の既定照合に依存しない |
| TEXT を含む複合 UNIQUE | MySQL の索引長を検討。長い Path は正規化 UTF-8 の digest を索引候補にし、原文比較で衝突検出 |
| FTS / 日本語 / ranking | SearchIndex 契約へ分離。DB ごとの全文検索結果が完全一致すると仮定しない |
| エラーコード | unique / FK / deadlock / serialization / busy を共通分類 |
| job claim / pagination | SQLite single writer、PostgreSQL/MySQL row lock + claim token、安定した keyset cursor |
SQL を全機能一度に書き換えず、スキーマ → Object/Path/Revision/Asset → 認証/ACL →
タスク/CalDAV → event/outbox/通知 → City/検索/管理の順に契約テストを追加する。
全 repository の通過前は PostgreSQL/MySQL を本番選択可能と表示しない。
外部 RDB を導入しただけでは HA ではない。job lease/fencing、可変正本、鍵共有が別の条件。
### DB 移行
既存データを上書きするのではなく、新規 target DB へ schema 作成 → snapshot import →
UUID/件数/参照整合性/ACL検証 → 停止時間内の差分反映 → 接続先切替を行う。
最初は書き込み停止で一貫性を確保し、オンライン dual-write は採用しない。
移行元は保持。新 DB に書き込み開始後の単純な DSN 戻しはデータ喪失となるため禁止する。
## 6. Redis / KV
初期用途は TTL 付き共有キャッシュ、短時間の同一処理集約、通知配信の補助。
永続ジョブ・通知 Inbox・失効情報・監査 outbox は RDB 側を正本とする。
- key は instance / domain / provider / schema / policy epoch を含める。
- 認可を含む表示 cache は principal と権限 version を分離し、古い ACL で許可しない。
- 接続 pool、TLS、ACL、タイムアウト、value 上限、TTL jitter、hit/miss/eviction を持つ。
- cache 障害は安全な DB 参照へ限定的に縮退し、全リクエストの stampede を防止する。
- Redis Pub/Sub は配送保証に使わない。通知の取りこぼしは DB Inbox から再取得する。
- 分散ロックだけで正本の排他を保証しない。多ノード更新は DB の fencing token を検証する。
- 永続化方式 RDB/AOF の運用と、再生成可能 cache のバックアップ不要性を区別する。
## 7. ファイルストア別の対応
| backend | 導入方法 | 必須条件・制限 |
| --- | --- | --- |
| local | 現在の data/documents と互換 | fsync、原子的な no-replace publish、ルート内アクセス |
| S3 compatible | SDK adapter、bucket/prefix/region/endpoint | 条件付き作成、range、checksum、multipart 中断回収、TLS |
| over SSH | 原則 SFTP adapter。SSHFS mount は別の検証対象 | known_hosts 固定、専用 user/root、host-key 変更を拒否、shell コマンド文字列禁止 |
| NFS | OS/Compose で管理者が mount、アプリはパスを利用 | protocol/mount/lock/durability を環境別認証、切断時に失敗させる |
| SMB | 同上、CIFS mount または後続 adapter | case-sensitive key 契約、rename/link/flush の実環境試験 |
### S3
SDK の標準 credential chain と secret reference を使い、本文や manifest に資格情報を埋め込まない。
bucket は private を既定とし、公開 URL と物理キーを分離する。
`If-None-Match: *` による作成、既存時の checksum 検証、`412` と通信障害の区別が必要。
S3 ETag は Document SHA-256 と見なさない。互換製品ごとに conditional/multipart/checksum を検証する。
upload は bounded spool または検証付き streaming とし、未検証データを final key へ公開しない。
LIST をバックアップの整合性境界にせず、DB snapshot の参照 manifest で必要な hash を列挙する。
障害中は書き込みを失敗させ、プロセスごとのローカル正本へ分岐させない。
### ネットワーク filesystem / SSH
SQLite の DB/WAL/SHM を NFS・SMB・SSHFS に置くことは禁止する。
共有可能にするのは、契約テストで検証した Document/正本 backend に限る。
アプリに mount 権限や任意 SSH コマンド実行権限を与えない。
mount が消えた際に空のローカル mountpoint へ書くことを防ぐ sentinel / device / mount-id 検証が必要。
context のキャンセルだけで、停止した NFS syscall を必ず中断できるとは扱わない。
独立 worker、I/O 上限、circuit breaker、管理者向け degraded 状態を設計する。
hard-link/no-replace や directory fsync のない共有領域を local backend として認定しない。
## 8. バックアップと export の区別
| 操作 | 目的 | 含めるもの |
| --- | --- | --- |
| backup/restore | 同一インスタンスの災害復旧 | DB snapshot、Document、カレンダー正本、設定、必要な鍵の暗号化保全 |
| export/import | Domain/Path/プロジェクトの移動・交換 | 許可範囲の内容・revision・asset依存・選択したメタ情報。秘密は既定で除外 |
| release/deploy | 実行コードの更新 | SemVer、Git commit、イメージ digest、schema互換条件。ユーザーデータとは別 |
バックアップ manifest は format_version、instance ID、アプリ SemVer、schema version、
各 DB snapshot、正本 generation、Document の hash/size、暗号化情報、完了状態を持つ。
全生成物を検証してから complete marker を発行する。部分生成を復旧可能と表示しない。
最初は全書き込み元(Web/API/CalDAV/CLI/同期 worker)を止める maintenance barrier を使い、
GC を pin して DB と可変正本を snapshot する。不変 blob のコピーはその参照集合で行う。
「DB はコピーしたが calendar.json は後から別の時点でコピーした」を許さない。
オンライン化は revision/outbox watermarks と snapshot pin 実装後の段階とする。
- SQLite:online backup API / 検証済み snapshot。稼働中の pages.db 単独 rsync はしない。
- PostgreSQL:論理 dump と必要に応じた physical backup/PITR を別モードにする。
- MySQL:InnoDB の consistent snapshot と migration/DDL 排他を確認する。
- Redis:再生成可能 cache は除外。独自永続用途を追加したら manifest へ明示する。
- 鍵・接続資格情報:別保護領域へ暗号化。復元に必要な鍵を同じ暗号化アーカイブ内だけに入れない。
- restore:新規領域へ展開・検証・dry-run、互換性確認、切替。通常 Web から稼働 DB を上書きしない。
保持期間、容量、転送帯域、暗号化、定期実行、リモート複製、リストア訓練を独立設定にする。
バックアップ削除は全世代を単純削除せず、増分依存と稼働リリースの復旧条件を確認する。
## 9. 手動スクリプト・CLI・Web の共通化
将来の `pageswiki-admin` / `pageswiki` 運用サブコマンドに処理を集約し、
編集可能な shell script は環境変数・設定ファイル・コマンドの薄い組み合わせにする。
スクリプトから直接各 DB のテーブルへ別々に書く方式は増やさない。
候補コマンド(**まだ未実装**):
```text
storage status / verify / migrate --plan / migrate --apply
backup create / list / verify / restore --plan / restore --apply
export --domain … --path … --format pageswiki-bundle
import --file … --plan / import --file … --apply
release verify / deploy --version vX.Y.Z --plan / deploy --apply
```
online CLI は共通 API と権限・監査・event queue を通す。offline は保守モード専用で、
直接 DB を開く現行 Python CLI は当面の互換/repair 経路として残す。
import はサイズ・件数・展開率上限、zip-slip、symlink/hardlink を検証し、試行計画を先に表示する。
UUID保持/新規採番、Path衝突、ACL継承、Cityサジェスト、部分失敗の再試行を明示選択にする。
Web バックアップは instance/campus 管理者向け。Domain export 権限と混同しない。
設定パネルには履歴・状態・検証結果をコンパクトに表示し、作成条件はダイアログに収める。
作成は既存 scheduler の `backup.create` / `backup.verify` event としてキューへ入れる。
API は `/_/api/v1/backup/`、ジョブ状態は既存 `/_/api/v1/event/` / `queue` を利用する案とする。
ダウンロードにも現在の認可、有効期限、監査、no-store を適用する。秘密付き archive を公開しない。
Web から任意の保存先パス・任意コマンド・任意外部 URL を指定できるようにしない。
release script は v0.1.0 で整備した digest 昇格を再利用する。
deploy は backup 検証 → image pull → maintenance/migration → health check → 切替。
DB migration 後の旧イメージへの自動 rollback は互換性が明示された場合だけ許可する。
## 10. 初回ようこそ画面
状態は `uninitialized → claimed → configuring → validating → ready`。
既存データのあるインスタンスには表示せず、DB 到達不能を未初期化と判定しない。
初期 DB 未作成でも使える bootstrap 設定は local protected file / secret mount に置く。
1. ホスト側で生成した短寿命・一回限りの setup token で管理者が claim(競合時は一人だけ成功)。
2. 単独 / controller / 外部 Campus 管理モードを選択。外部管理の名前等は従来どおり継承する。
3. Metadata DB、Document backend、canonical state、任意 Redis を設定。
4. TLS・資格情報・必要な保存操作を管理者指定 backend 内の専用 probe 領域で検証。
5. 最初の管理者、言語・タイムゾーン、FQDN、バックアップ先/保持方針を確認。
6. 設定を原子的に保存し migration/初期化を実行。成功後 setup token を失効し ready にする。
公開ネットワークで最初にアクセスした人を無条件に管理者にしない。
setup 完了後は token 再利用不可。機密欄の再表示・ログ出力をしない。
外部 Campus 自動参加など既存の非対話起動を維持する。
## 11. 段階別 TODO と受入条件
### S0:契約とローカル保存の是正
- [x] 不変 Document Store interface と既存キー規則を実装。
- [x] local の streaming 検証、no-replace publish、directory fsync、root 内アクセスを実装。
- [x] 現行 Store の保存・読み取り・サイズ・部分読み取りを接続。
- [x] 並行書き込み、既存破損、サイズ/hash不一致、キャンセル、パス逸脱をテスト。
- [ ] backup inventory / canonical state / secret / scratch の設定と寿命をコード上で分離。
### S1:移植準備
- [x] Open/Size/Window の context 付き API と主要 HTTP 配信への伝搬。
- [x] archive/preview/一覧サイズの直ファイルアクセスを置換し Materialize を導入。
- [x] ZIP 個別配信・画像/ZIP サムネイルを Reader/ReaderAt ベースへ変更。
- [x] 共有取得、キャンセル、容量/件数制限、破損、最終利用後の削除をテスト。
- [ ] 従来の Revision hydration/保存、一覧 DB クエリを含む全 payload API へ context を伝搬。
- [ ] Document の byte size を DB のメタデータとして確定し、外部 backend で一覧ごとの
Stat/HEAD が N+1 呼び出しにならないようにする(現状は既存のサイズ補完動作を維持)。
- [ ] Materialize の固定上限を設定化し、クラッシュ残骸の安全な回収・メトリクスを接続。
- [x] Document backfill の保存先 identity、UUID cursor、バッチ checkpoint、完了後の起動時走査省略。
- [x] SQLite migration runner の version/checksum/排他/rollback と旧 hash 移行のメモリ使用改善。
- [x] projection/resource/broadcast/browser-navigation/adapter-session/import の schema 定義集約、
既存データを保持した採用、条件付き列追加、schema assertion の契約テスト。
- [x] event queue/log schema の管理、起動時ジョブ復旧と schema 処理の分離。
- [x] 読み取り専用 `schema status|check` CLI(JSON/終了コード/履歴・契約検査/対象外範囲の明示)。
- [ ] backfill を保守 CLI / event queue / 進捗 UI へ接続し、非同期実行時の配信契約を整備。
- [ ] 既存 Ensure*Schema を migration runner へ段階移行し repository 別 SQL 契約テストを整備。
- [ ] deployment profile で SQL / Document / canonical / cache / secret の設定を分離。
### S2:外部 backend
- [x] PostgreSQL 接続層と独立した migration runner(アプリの backend 切替は未接続)。
- [x] Object/Path/Revision/Asset の共通 metadata Repository と空 DB 用スキーマ、SQLite/PostgreSQL 共通契約テスト。
- [x] 既存 Store の Campus/Domain 取得・ホスト解決・ドメイン別設定・Campus 作成/更新の native SQL 移植と共通契約テスト。
- [x] 管理者グループの初期化・メンバー更新・継承切替・projection・派生所属とセッションの失効を共通 SQL と transaction に移植。
- [x] 一般グループの作成・一覧・メンバー一覧・Path 権限設定、直接 Role binding と Group 権限の付与判定、Principal 状態更新と失効を共通 SQL に移植。
- [x] 初回 owner・パスワードアカウント・プロフィール・セッション管理、TOTP、外部認証の設定と Identity 紐付け、CLI 認証引き継ぎの DB 処理を移植し、SQLite/PostgreSQL 共通契約テストを追加。
- [x] 認可と読み取りナビゲーションの Locality 制限、City 所有者・公開範囲の上限制約、ユーザー/グループ ACL 更新、保護 Path/City 構造の DB ガードを移植。
- [x] 公開 manifest・自動公開・匿名 navigation、承認要求、ユーザー領域とプロフィール連絡先の公開制御を native SQL に移植し、共通 DB テストを追加。
- [x] Domain 作成/更新/削除と Campus 削除、管理者継承、連携トークン・instance 登録・署名 manifest の DB 処理を移植。
- [x] 通常 Revision 保存・履歴取得・履歴復元の Store 境界と HTTP 呼び出しを native metadata Repository に接続し、合成データで保存・競合・故障時の rollback を検証。
- [x] Path の再帰移動・コピー・snapshot 付き一括削除、alias/primary link と navigator の DB 処理を移植。
- [x] City map・所属 Page・Path context・health・監査履歴の取得、タイトル・境界変更、Spot 整理(移動・統合)を移植。
- [x] Asset の一覧・参照・履歴、作成/更新・復元・削除を移植し、楽観ロックと履歴保存失敗時の rollback を検証。
- [x] City の個別作成・配置・relation・再帰削除、一括変更計画の preview/apply、自動生成候補と名前競合の問い合わせを移植。
- [x] Browser・children・Path 補完・権限付き Object metadata 一覧を移植し、native canonical HTML の H1 と複数 Store 間の children cache 失効を検証。
- [x] アーカイブ import のセッション・計画・journal・Path rollback を移植。全 DB の SQLite→PostgreSQL インポートとは別機能。
- [x] タスク・プロジェクトの保存/取得/履歴/階層付き一覧/削除、DAV resource・collection・資格情報・既定リスト名の Store 操作を移植し、両 DB で契約を検証。
- [x] タスク個人設定、作業時間の開始・終了・訂正・取消と監査履歴、Pomodoro と日次集計、ダッシュボード配置・達成率、予定枠の DB 予約を移植。
- [x] 通知 Inbox の保存・重複排除・取得・既読、期限/着手日の通知配信、タイマー完了、活動 journal の outbox 補完処理を移植。scheduler と Push 配信は別途接続する。
- [x] タスク capture と Wiki 同時作成、削除後の明示的再作成、プロジェクト配下のメモ作成を移植。受付記録・本文参照・Path・outbox の原子性を検証。
- [x] 日次メールの送信予約、本人の同意・権限確認、送信履歴、明示的再試行、保持期限処理を移植。SMTP worker と scheduler は別途統合する。
- [x] カレンダーの再構築可能な月別索引、予定の取得・更新・削除、DAV resource 操作、タスク予定枠と日次予定の cache 参照を移植。正本 ICS と manifest の形式は維持する。
- [x] 連絡先の保存・検索・削除・履歴復元・export、CardDAV の resource 名・差分同期・metadata inventory と資格情報失効を移植。
- [x] ブログ・日記の設定、記事作成・登録・解除・一覧、投稿受付の重複排除、公開タイトルと別 Domain への射影設定を移植。本文と埋め込み Asset 参照の固定、監査失敗時の rollback を検証。
- [x] RSS/FreshRSS の購読元・既読/スター・記事 cache・分類・購読 import・Wiki 取り込みと受付記録、外部操作の claim・確認・履歴を移植。scheduler 登録は別途接続する。
- [ ] 通常 HTTP/scheduler/CLI 起動を経由した認証・公開・federation の PostgreSQL 統合試験。
- [x] 読み取り専用の移植診断 CLI と、対応済み core の catalog / 履歴検査。
- [x] 停止状態の core SQLite→PostgreSQL→SQLite 往復リハーサル、内容指紋・採番・参照・Document の検証。
- [ ] Object/Path/Revision/Asset の全 Store 操作と関連正本更新の接続、既存 DB 移行、共通統合テスト。
- [ ] PostgreSQL の全 repository 移植と SQLite との共通機能テスト。
- [ ] MySQL の DDL/索引/照合順序/同時書き込み試験。
- [ ] S3 adapter と互換サービスで range/条件付き作成/破損/切断/容量制限を検証。
- [ ] SFTP adapter と host-key 検証、NFS/SMB/SSHFS の契約検査と mount 喪失検知。
- [ ] Redis cache adapter と停止時の制限付き縮退、policy epoch による失効。
- [ ] mutable canonical CAS と metadata 参照の回復プロトコル、HA の fencing。
#### PostgreSQL 対応の実装順序
2026-11-14 時点では `internal/db.OpenPostgreSQL` と
`ApplyPostgreSQLMigrations` を追加した。既存の `Open`、`Migrate`、通常の Store 初期化、
通常起動、DR、CLI は引き続き SQLite 用であり、PostgreSQL を本番選択可能にはしない。
利用者の DB を自動変換せず、既存 migration の checksum も変更しない。
接続には pgx の database/sql 実装を使用し、DSN はインスタンスの秘密設定として扱う。
既定で検証付き TLS と平文 fallback の禁止を要求する。開発専用の
`AllowInsecure` を明示した場合だけ非検証接続を許す。接続確認の timeout、
pool の上限、connection の寿命を設け、失敗時は pool を閉じる。
エラーは SQLSTATE と操作名だけを公開し、DSN、SQL、サーバの詳細メッセージや
constraint 内の個人情報をエラー文字列へ含めない。
PostgreSQL 用 migration は SQLite の SQL 自動翻訳ではなく、独立した append-only 定義とする。
BIGINT の epoch ms、ネイティブの `$1` 引数、明示した conflict target を使う。
runner は READ COMMITTED transaction と共通の transaction-level advisory lock で
ledger の初回作成を含めて直列化する。異なる component にも同じロックを使う。
DDL、checksum 履歴、最新 assertion の検証を同じ transaction に含め、
失敗時は rollback、正常終了時は commit と同時にロックを解放する。
未知の新しい履歴、欠けた version、変更された定義は適用を停止する。
| 順序 | 範囲 | 完了条件 |
| --- | --- | --- |
| 1 | 接続と migration | 実 PostgreSQL で並行適用、rollback、履歴不一致、lock 待ちキャンセルを検証 |
| 2 | Object/Path/Revision/Asset | Domain 分離、UUID 不変性、revision 保存、再帰 rename、hash 参照の SQLite 共通契約を通過 |
| 3 | 認証と ACL | ユーザー、グループ、セッション、公開範囲の共通契約を通過 |
| 4 | タスクと CalDAV | プロジェクト所属、VTODO、ETag と競合更新、通知を検証 |
| 5 | ジョブと通知 | claim token、lease、row lock、outbox と重複処理耐性を検証 |
| 6 | City と検索と管理 | rowid/PRAGMA/FTS5 依存を分離し、安定した順序・検索・schema 診断を検証 |
| 7 | 既存データ移行と運用 | 停止状態の export/import、件数・参照・hash 検査、restore rehearsal、起動設定と readiness を接続 |
#### 既存 Store の Campus と Domain と設定の移植
`internal/store` に backend を保持し、既存 API から native PostgreSQL の SQL を使える
経路を追加した。既定値は SQLite とし、従来の Store constructor と最小 fixture の
振る舞いを維持する。SQL の `?` を一括変換せず、query 構築時に placeholder を生成する。
ホスト名の判定は SQLite の `instr` と PostgreSQL の `strpos` を明示的に分ける。
移植済みの範囲は次のとおり。
- Campus の既定値取得、UUID 取得、一覧、作成と更新。
- Domain の既定値取得、UUID 取得、一覧、件数、Host 解決、実効 FQDN の取得。
- Domain ごとの設定の取得と UPSERT。欠けた設定は従来どおり空文字とし、更新時刻は既存の秒単位を維持。
- 既存 Store の Path 解決で backend を選択し、Domain が local であることを確認して共通 Repository を呼ぶ。
Campus の FQDN と Domain の相対ホスト名・FQDN 指定を同じ規則で解決する。
未知の Host を既定 Domain へ fallback せず、無効な Campus/Domain と remote Domain の
ローカル名前空間へのアクセスを既存の取得規則に従って拒否する。
Campus 作成・更新では、移植済み writer が同じ namespace lock を使う範囲で、
ホスト名競合の検査と書き込みを一つの transaction に入れる。
PostgreSQL では同一 DB の advisory lock、SQLite では書き込みロックを検査前に取得する。
transaction の期限とキャンセルは内部の SQL 呼び出しまで伝搬する。
Domain/Campus の context 付き取得 API を追加し、HTTP のリクエスト単位の Host 解決でも
request context を利用する。PostgreSQL の SQL/driver/Scan エラーから個人情報や設定値を
出力しないようにし、入力フォームへ返せる固定の validation message は区別して保持する。
PostgreSQL の初期スキーマは `store-namespaces` migration として独立させる。
対象は `campuses`、`domains`、`config`、`personal_appearance` のテーブル定義と索引であり、
後者の個人外観 API の移植まで完了したという意味ではない。
既知の列不足や適用済み定義の不一致は停止し、既存 SQLite の ALTER/adopt 処理は流用しない。
既定 Campus/Domain の初期化は transaction で直列化し、並行実行時の重複と関連付けの欠落を防ぐ。
これは旧インスタンスの全データを取り込む import 処理ではない。
Domain 作成・更新は Campus/実効 Host/配置先の検査、Domain 本体、既定 locale、
管理者グループ作成と所属 projection を同じ管理用 writer lock と transaction に含める。
同じ実効 Host の同時作成は一つだけ成功し、別 Campus への移動は旧 Campus 由来の管理者権限を取り消す。
依存テーブルや projection の障害時は Domain と設定も rollback する。
Domain/Campus 削除の参照・最終要素検査も transaction 内で実施する。
Campus 削除では連携 token、instance と capability、署名 manifest の checkpoint も削除する。
`store-federation` は token hash、instance identity、manifest 採番と受信 checkpoint を保持する。
登録と token 失効は同じ lock を使用し、登録後に失効済み token を再利用できない。
署名の検証後、初回 controller fingerprint の固定、旧 revision と同一 revision の異なる内容の拒否、
受信 Campus/Domain/管理者継承と checkpoint の保存を一つの transaction で扱う。
`store-domain-entry` は manifest v2 の許可済み entry 設定と日記/ブログの有効化・prefix を保持する。
これは日記/ブログ本文の新規作成・検索・projection repository 全体の移植完了ではない。
現時点の PostgreSQL Store は component 統合テスト内でのみ構築する。
本番用 constructor と起動フラグはまだ解放せず、通常のサーバーは SQLite のままとする。
core 限定インポートの対象も拡張しておらず、namespace を含む DB は引き続き対象外として拒否する。
#### 認証と管理者グループの移植
`store-auth-foundation` の native migration は Principal、Identity、Domain membership、
Role、直接 Role binding、Capability grant、Group、Group member と Campus 管理者継承の
provenance を定義する。アバターは BYTEA、時刻は BIGINT の Unix milliseconds、
識別子と一意制約の比較は C collation とする。既存テーブルの暗黙の取り込みや修復は行わない。
適用済み migration の列検査が失敗した場合も既存 Principal を保持したまま停止する。
既存 Store の `IsBuiltinGroupAdmin` と `IsCampusAdmin` は SQLite と PostgreSQL の
両方で動作する。context 付き API は SQL エラーと拒否を区別し、従来の bool API は
DB 障害時も権限を与えない。Domain と membership の対応、Principal・membership・Group
の有効状態、Domain の enabled、owner/manager role を同じ SQL で検査する。
SQLite と実 PostgreSQL の共通テストで状態変更、越境所属、キャンセル、DB 障害を検証する。
`EnsureBuiltinAdminGroups`、メンバーの追加・更新・削除、`SetCampusAdminInheritance`、
`ProjectCampusAdminMemberships` は両 DB 共通の実装を使う。
グループの名前・UUID による取得と member role の参照も backend に対応する。
PostgreSQL では namespace 更新と同じ advisory lock、SQLite では読み取り前の
DB writer lock を使い、元の grant 更新と継承先の再計算を同一 transaction に含める。
context 付き API の期限は内部の SQL まで伝搬する。
継承の入力は独立した grant に限り、派生 grant を新たな継承元にしない。
複数の継承元のうち最も強い role を実効値とし、継承解除時には弱いローカル role が再び現れる。
派生した membership のみを追跡し、独立した group/role binding で採用済みの所属と session は保持する。
派生権限しかない所属は削除し、その Domain の session を同じ transaction で失効する。
再有効化しても失効済み session は復活させない。
最後の独立 owner の並行削除、継承先での inherited-only grant 削除、owner の通常更新による降格は拒否する。
Role からの初期 grant は記録済みの migration marker で再投入を防ぎ、明示的に取り消した権限を
再起動で復活させない。Domain の異なる Role binding と別 Domain を指定する manage grant は初期 owner にしない。
native migration の v2 には失効処理に必要な `auth_sessions` と索引を追加する。
管理者継承の共通テストは合成 session 行で取り消しと保持を検査し、
projection 後半の故障注入でメンバー追加・削除・継承切替のすべてが rollback することを確認する。
一般グループの作成は owner の有効な Domain membership と active な Principal を確認し、
Group、owner member、派生 membership の独立所属への採用を同一 transaction に含める。
一覧の `domain` visibility は単に Principal UUID があるだけでなく、その Domain で有効な所属を要求する。
`members` visibility とメンバー一覧、role 参照、Path 権限評価でも membership の Domain 一致を検査する。
別 Domain の不正な owner 行を最後の独立 owner の代わりに数えない。
一覧は EXISTS で重複を避け、表示名・名前・UUID による安定順を持たせる。
native migration の v3 は `group_permissions` とメンバーの Identity 参照用索引を追加する。
権限設定は既存 Group を要求し、同じ Group/Path の設定を upsert する。
`read`、`read_write_once`、`read_write`、`upload_only` の既存 capability と literal Path 境界を保持する。
SQL の `%` と `_` を wildcard として扱わず、readonly Principal は read だけを許す。
直接 Role binding の付与判定も backend に対応し、Domain の異なる Role を拒否する。
exact Object モードでは Domain 全体や wildcard の grant を採用しない。
この低水準判定は Locality 制限を代替しない。`AuthorizeContext` と
`AuthorizeExactObjectContext` は Role/Group grant と Locality cap、Object の別名・別 Domain 制限を
同じ read-only transaction で評価する。PostgreSQL は REPEATABLE READ を用い、
ナビゲーション用 `LoadReadPathPolicyContext` も同じ snapshot 契約を持つ。
公開コンテンツの匿名読み取りとユーザー領域の公開制約も、下記の同一 snapshot 契約を使う。
アカウント作成時の Role/binding 書き込みは下記の transaction に含める。
それ以外の federation・管理操作からの Role/binding 書き込みは別途移植する。
`SetPrincipalState` は管理者継承と同じ writer lock を利用する。
グローバルな Principal の状態更新、active 以外への変更による全 Domain の session 失効、
派生管理者権限の再計算を同じ transaction に含め、失敗時は全体を rollback する。
既に失効した session の失効時刻を上書きせず、active へ戻しても session は復活させない。
アカウント作成は Principal、Identity、Credential、Domain membership、Role/binding を
同じ transaction に含める。初回 owner は管理者グループへの projection まで含め、
途中の失敗時にはアカウントも残さない。並行 bootstrap は一つだけ成功する。
password hash の計算は writer lock を取得する前に行う。
native migration v4〜v7 は Credential、Challenge、Provider 設定、CLI 認証引き継ぎを追加する。
v8 は既存の Group/Role mapping と認証監査ログ用テーブルを追加する。監査イベントの新しい発行機能を追加する変更ではない。
適用済み migration の SQL/checksum は変更しない。
ブラウザ/API session の発行は停止・継承失効と同じ writer lock を利用する。
token の用途 prefix を hash 対象に含め、Domain 境界と有効な所属を検査する。
プロフィールと avatar の読み書き、Domain のアカウント一覧、session 一覧・失効も両 DB に対応する。
TOTP の登録確定と counter 消費は同じ transaction 内で検証・更新する。
SQLite の JSON 関数を PostgreSQL 上で代用せず、Go 側で counter を読み、writer lock で
再利用を防ぐ。外部認証の設定保存では、空の secret を指定した更新は UPSERT 内で
現在の暗号化 secret を保持する。外部 Identity の競合で別 Principal に紐付け直さず、
重複するメールアドレスや表示名は曖昧なマッチとして拒否する。
CLI の認証要求は同時受付でも件数上限を超えないよう transaction で直列化する。
承認消費と API session 発行は一括 commit し、発行失敗時には承認も rollback する。
同時 exchange の成功は一つに限り、poll 間隔・origin・Domain・trusted choice を保持する。
共通テストは合成データだけを用い、実際の LDAP/OIDC/SMTP サーバーには接続しない。
`store-city-foundation` は階層・所有者・公開設定・監査記録・公開 manifest の保存用 schema を持つ。
`CityGovernance`、所有者候補検索、`ChangeCityGovernance`、`LocalityAccess` は native SQL を使う。
変更前に管理者継承と同じ advisory lock を取得し、epoch/topology の比較、上位の公開範囲、
所有者の委任権限を検査する。preview は rollback し、実変更は policy・epoch・監査を一括 commit する。
上位管理者の ACL を下位所有者が広げることは拒否し、対象者の削除などの縮小だけを許可する。
`store-locality-foundation` は Path と設定のガードに加え、Zone/Spot/Street所属の変更を
保護する PostgreSQL trigger を持つ。ACL のある Domain で enforcing を解除できず、
保護 Path の移動・削除・別名による脱出を拒否する。新規 Object を保護範囲内に作成することは許可する。
Path の比較には C collation の文字列範囲を使い、`%`、`_`、大小文字、日本語を LIKE の wildcard としない。
trigger を無効化・削除した状態は migration の assertion と ACL 変更時の検査で拒否する。
将来の City/namespace writer も、行ロックより先に同じ管理用 lock を取得する順序に統一する。
共通テストでは上位公開範囲の制約、所有者委任、ACL 縮小、同時変更の単一成功、
preview の非永続化、監査失敗時の rollback、保護 namespace、失効後の次リクエストを確認する。
schema の追加は City 全体の対応完了を意味しない。通常 HTTP ハンドラとの PostgreSQL 統合試験、
City 全変更系と他の管理経路からの Role/binding 操作の監査は残る。
既存 SQLite の他の mutation から呼ばれる旧 transaction wrapper は
SQLite 用のままであり、それらの PostgreSQL 化は呼び出し側の lock 契約も含めて行う。
`EnsureAuthSchema` は PostgreSQL の認証・Locality schema 初期化へ接続済み。
管理対象 migration の未移植 component は `ErrPostgreSQLComponentNotReady` で拒否し、
SQLite migration runner を PostgreSQL 接続へ流さない。本番用 PostgreSQL Store は未公開のままとする。
#### 公開とユーザー領域の移植
`store-publication` は公開 manifest の失効と navigation generation 用 trigger を持つ。
匿名 Revision 読み取りと navigation は、明示承認と自動公開候補を同一 read-only snapshot で確認する。
有効な Campus/Domain、HEAD、hash、別名、公開範囲、公開者の状態を検査し、
本文更新・別名追加・権限変更後の次リクエストに失効を反映する。
上位の手動承認必須設定は下位の自動公開を止める。
PostgreSQL の navigation trigger は statement 単位で更新し、generation を行数ではなく失効 token として扱う。
`store-publication-approval` の要求作成は domain/idempotency key の競合を UPSERT で処理する。
承認は状態・generation・期限を検査し、decision 記録と状態更新を一括 commit する。
同時承認の成功は一つだけで、期限切れ整理ジョブの実行前でも期限切れ要求は承認できない。
`store-user-space` は profile/avatar/root/descendant の公開設定、Path ごとの縮小例外、監査記録を持つ。
公開読み取りは有効な本人所属と Domain の上限、本文 HEAD を同じ snapshot で評価し、
別名付き Object は匿名公開しない。例外 Path の改名は同じ所有者の namespace に制限し、
改名・削除に policy を追従させる。policy 更新と監査記録は一括 commit する。
`store-profile-contacts` は電話番号を Principal の一般情報と分離し、
本人の同意・profile 公開設定・Domain の上限を満たす場合だけ匿名へ公開する。
競合した version は拒否し、非公開時は値だけでなく version/visibility も返さない。
既存 SQLite の同一時刻 Revision は `rowid` で HEAD を決定する一方、native PostgreSQL は UUID を用いる。
新規 native 保存は時刻を単調増加させるが、旧 DB の同時刻データにはその保証がない。
全件 import は言語別 HEAD とその参照先を移行前後で照合し、順序の保存方法を確定するまで
本番切替を許可しない。core の往復試験だけでこの条件を満たしたと判断しない。
#### 共通 metadata Repository の実装範囲
`internal/metadata` は Object 作成、Domain ごとの Path 解決と alias、再帰移動、
言語別 Revision HEAD の比較更新、履歴 UUID の参照と非破壊復元、Asset HEAD と
履歴の原子的更新を提供する。SQL の placeholder を組み立て時に生成し、
SQL 文字列の一括置換は行わない。DB には Document 本文を保持せず、
低水準の `AppendRevision` は呼び出し側が Geduldh へ先に検証・永続化した SHA-256 を公開する。
`SaveDocument` は参照固定と payload 永続化も含めた保存パイプラインを提供する。
Revision の `body` 列は既存形式との橋渡し用の空キャッシュであり、正本ではない。
PostgreSQL の書き込みは Domain 単位の transaction-level advisory lock を取得し、
Revision ではその後に Object 単位の lock も取得する。lock の取得順を統一し、
異なる Object の保存でも Domain 内の outbox sequence を直列化する。
アプリ用の `NewApplication` は、その前に namespace 管理と共通の advisory lock を取り、
有効な Campus と Domain、local 配置を transaction 内で再確認する。
順序は namespace 管理 → Domain → Object とする。本文の検証・永続化 I/O 中には取得しない。
SQLite は読み取り前に書き込みロックを取得する。
全 writer が同じ契約を使う前提で、プロセス内の mutex に依存せずに HEAD を比較する。
Revision の時刻は同一言語の前の値より必ず後にし、順序付けに隠れた rowid を使わない。
復元は新しい Revision UUID で追加し、過去の Revision を変更しない。
埋め込み Document の参照も履歴から引き継ぎ、現在の Asset HEAD へ置き換えない。
再帰移動は移動先が空であることを検査し、一つの UPDATE で配下を移動する。
全 Path のメモリ展開や一件ずつの SQL 発行はしない。Path は SQLite の binary、
PostgreSQL の C collation とし、配下の検査は索引を使える文字列範囲で行う。
日本語、大小文字、`%`、`_`、仮想フォルダ、同名の別 Domain を区別する。
同一 Domain 内の alias 追加は既存 Path を上書きしない。Domain を越えるリンクの
取り扱いは認可・共有の移植時に別途実装する。
`InitializeFresh` は専用 migration 履歴で管理する空 DB/schema 用の初期化である。
既存の未管理テーブルがある場合は採用や変換をせず失敗し、既存データを保持する。
再実行時には必要なテーブルと列の存在を SELECT assertion で検査し、不足時は停止する。
列型、照合順序、索引、一意制約の完全な catalog 検査はまだ対象外である。
既存 Store の初期化からは呼ばない。Store の PostgreSQL 分岐には Path 解決、
Object/Page 作成、通常 Revision 保存と履歴復元を接続した。アプリ用の Page 作成は
Object・origin・Path と `page.created` を一括 commit し、イベント保存失敗時は全て rollback する。
`NewApplication` 自体は通常起動の constructor や認可処理ではない。
保存パイプラインの実装と、変更系のアプリ接続前の残件は次のとおり。
- [x] DB 非依存の Asset freeze を切り出し、既存 SQLite Store からも利用。
- [x] 共通 Repository の `SaveDocument` で Document 永続化、埋め込み Asset 検証、参照記録を接続。
- [x] 共通 Repository の Revision 保存と activity outbox の追加を同じ transaction に統合。
- [x] 通常保存・復元 HTTP API を Domain 明示の Store 境界へ接続し、PostgreSQL 分岐から新パイプラインを呼び出す。
- [x] 言語別 HEAD・履歴 cursor・Document 参照一覧の native SQL と欠損 payload の失敗処理を接続。
- [x] 通常の Path 再帰変更、native filename Revision とコピー時の埋め込み参照保持、navigator の追従を接続。
- [x] Asset Store API の native SQL と履歴復元を接続。
- [ ] Web/API/CLI の変更系を新保存パイプラインへ切り替え。
- [ ] Path/City の残る入口・reconciler と関連 metadata を監査し、通常 HTTP と cache invalidation を統合試験。
- [ ] 既存 Store の残りの取得・一覧・専用リンク操作・import writer を移植。
- [ ] 既存 schema の移行計画、schema drift の assertions、整合性検査を整備。
- [ ] 同時 GC との pin 契約、巨大 Asset の検証 I/O の予算と再検証 cache を整備。
`internal/documentrefs.Freeze` は可変 `asset:` を HTML の参照属性から解決し、
SHA-256 URL と出自属性へ固定する。同一 address の解決と同一 hash の参照記録は重複させない。
通常テキスト、コード例、非 HTML payload は解決せず、変更不要の HTML token は元の byte 列を維持する。
既存 Store は従来の resolver を adapter として使い、PostgreSQL 用の保存では Domain を明示した resolver を使う。
外部 URL へアクセスする機能ではない。
`SaveDocument` は対象 Object の Domain 内の Path と言語別 HEAD を先に確認し、
解決した埋め込み payload を検証してから、凍結済み Document を Geduldh へ永続化する。
この間に DB transaction や lock は保持しない。その後に HEAD を再比較し、
Revision、`revision_document_refs`、`revision.created` の pending outbox、型別 watermark を
一つの transaction で確定する。outbox の sequence は型別 watermark から割り当て、
増え続けるイベント履歴全体を走査しない。イベント配信と worker lease の移植は別工程である。
アプリ用 Repository は未紐付け Object に限り作成元 Domain の origin を認め、
create/save/bind の順序を維持する。別 Domain に Path が存在する Object へ origin だけで書き込めない。
Object のみを渡す旧呼び出しは所属 Domain が一意の場合に限り解決し、複数なら明示指定を要求する。
これは認可の代替ではなく、HTTP 側の read/write 権限検査は維持する。
`SaveRevisionContentInDomain` は期待 HEAD の有無を区別する。空文字の期待値は未作成を要求し、
期待値なしは無条件 append とする。CAS 失敗を無条件 append で自動再試行しない。
PostgreSQL の `RestoreRevisionInDomain` は過去の本文と埋め込み参照の payload を検証し、
現在の Asset HEAD を再解決せず新しい Revision に引き継ぐ。
DocumentRoot を必須とし、正本の欠損を空の DB body cache で補修しない。
SQLite の既存 writer と復元の参照固定動作は維持しており、その統一は別の変更単位とする。
Path の native 変更処理は namespace 管理 lock を取得してから snapshot を再検証する。
移動・コピー・一括 unlink は最大 10,000 Path、30 秒の transaction 予算で実行し、
`%`・`_` をワイルドカードにしない索引範囲を使う。予算超過時に部分適用はしない。
再帰移動では City 境界、ユーザー領域の公開例外、保存した navigator の Path を同じ transaction で更新する。
既存の locality ACL によって保護された namespace の移動・削除は引き続き拒否する。
ACL を自動的に別の Path へ拡張する機能や DB guard の迂回は追加しない。
公開 manifest と navigation generation は既存の native trigger で失効する。
native のファイル名変更は、言語別 HEAD の参照 hash を保つ新 Revision を追加する。
コピーでは新 Object/Revision UUID を割り当て、全 Revision と埋め込み参照の対応を同じ transaction で複製する。
本文 blob は再利用する。unlink は履歴と blob を消さず、City の定義も自動削除しない。
コピー履歴で同時刻の旧 HEAD を維持する条件は、全件 import の順序問題と合わせて確認する。
City の読み取りは PostgreSQL の repeatable-read snapshot を利用する。
整理操作は topology version を管理 lock 内で照合し、Page placement、Spot relation、監査記録を一括更新する。
Page の URL は Spot 整理では変更しない。境界検査は最大 4,096 node に制限し、
Spot 整理の既存の選択数・展開 Page 数・relation 数上限も維持する。
Asset 復元は payload の hash を検証してから期待 HEAD を比較更新する。
削除は mutable Asset を取り除くが、履歴と既存 Revision からの参照は保持する。
payload 永続化後に競合や DB エラーが起きた場合、参照のない不変 blob が残ることは許容する。
同じ hash を別 writer が利用する可能性があるため、保存失敗時に blob を削除しない。
参照のない blob の回収は pin と保持期間を持つ GC の役割とし、同時削除を行う構成では
pin 契約の接続が済むまで新パイプラインを有効にしない。
portable core の v1 定義は変更せず、参照と outbox のスキーマを v2 として追加した。
試験用 v1 の既存行を維持した移行、DDL 途中失敗時の rollback、再試行を共通テストで確認する。
これは本番 SQLite からのデータ移行機能ではない。
既存 SQLite Store では、Revision の outbox 用 Domain 取得時に未知の SQL エラーを
無視しないよう是正した。outbox 自体がない最小 fixture は従来どおり扱うが、
outbox がある状態での取得・書き込みエラーは Revision と一緒に rollback する。
共通テストでは Domain 分離、言語の分離、同時 CAS、重複作成時の orphan 防止、
Revision の不変性、復元時の競合、Asset 履歴の故障注入 rollback を検証する。
保存パイプラインでは payload 書き込み失敗、埋め込み検証失敗、保存 I/O 中の別編集、
参照・outbox の故障注入、異なる Object の並行 sequence 採番も検証する。
これらは変更系 Web/API の PostgreSQL 対応完了を意味しない。
`PAGESWIKI_TEST_POSTGRES_DSN` に使い捨て PostgreSQL の URL を指定すると、
`go test -race -count=1 ./internal/db ./internal/metadata ./internal/documentrefs` が実 DB と参照固定のテストを実行する。
各テストはランダムな schema を作成し、終了時にその schema だけを削除する。
試験用ユーザーには CREATE SCHEMA 権限が必要で、本番 DSN は使用しない。
DSN を指定しない通常テストでは実 DB 部分だけが skip されるため、
PostgreSQL 対応のリリースゲートでは DSN 指定を必須とする。
初期検証対象は PostgreSQL 17。最低対応版の確約は CI matrix の整備後とする。
展示環境では metadata の PostgreSQL 化だけで NFS 対応完了とはしない。
Document の no-replace publish と directory fsync、カレンダー正本の lock と atomic rename、
秘密鍵とバックアップの配置を別々に検証する。PostgreSQL 自体の PGDATA を
未検証の共有 NFS へ移すことで SQLite の問題を置き換える運用は採用しない。
DB 用の適切な永続領域または外部 PostgreSQL を確保する。
#### 移植診断と停止状態の往復リハーサル
`pageswiki schema portability --db FILE --json` は既存 SQLite を読み取り専用で開き、
テーブルの担当領域、未対応テーブル・view・trigger・index、portable migration 履歴、
既知 core の catalog の差を報告する。行の値、DDL 本文、DSN、秘密鍵は出力しない。
DB がなければ作成せず終了し、初期化や migration は行わない。
アプリ全体が未対応の間は `application_ready=false` と終了コード 1 を返す。
`core_compatible=true` は下記の限定リハーサルに必要な契約であり、本番移行の許可ではない。
未対応テーブルを削除してこの診断を通すことはしない。
`InspectPortability` は SQLite では既知 core の生成 DDL と索引を厳密に照合し、
PostgreSQL では列型、NOT NULL、default、collation、identity、主キー・一意制約・外部キー・CHECK、
通常索引の定義と有効状態、sequence の設定を検査する。未知の unique index も無視しない。
PostgreSQL の RLS、独自 policy・trigger・routine・rule・sequence、継承・partition 等の未移植の状態は拒否する。
trigger は情報スキーマの権限による非表示に依存せず catalog から確認する。
PostgreSQL で検査する範囲は現在の schema であり、別 schema のアプリを含む全 DB の認証評価ではない。
backend 固有の migration ledger は checksum を検査するが、相手側へコピーしない。
`CloneCoreForRehearsal` は内部テスト用の core コピーであり、本番用 CLI には公開しない。
対象は Object、origin、Path、Revision、Asset、Asset 履歴、Revision の Document 参照、
activity outbox と型別 watermark の 9 テーブルに限る。認証、設定、タスク等の
追加テーブルがある実稼働 DB は拒否する。全 writer と GC の停止を呼び出し側の前提とし、
オンライン移行や二重書き込みを行う機能ではない。
コピーでは一つの source snapshot から主キー順に行を読み、型付きの値を保って
空の staging DB/schema に挿入する。一度に保持するのは一行分であり、最大の一行自体の
メモリ使用量は別の制約になる。移行元の DB を変更せず、移行先が空でない場合、
同じ DB を別 connection pool から指定した場合、未知の schema がある場合は拒否する。
移行先の全 core テーブルを保護し、途中でエラーが起きた場合はコピーした全行を rollback する。
文字コード不正、NUL、TEXT 列の BLOB、整数型の不整合、参照欠損を黙って変換しない。
照合は件数だけではなく、テーブル名・列順・主キー順の各行を長さ付きで SHA-256 に入力する。
64bit 整数を浮動小数へ変換せず、日本語、大小文字、異なる Unicode 表現、`%`・`_` を保つ。
履歴の採番は現存する最大 ID と generator の保持状態の両方から次の値を決め、
過去の ID が再利用されないようにする。PostgreSQL では非 transactional な `setval` ではなく、
コピー transaction 内で identity を `RESTART` する。
参照先の不変 Document は、別途保持する同一の Geduldh Store で SHA-256 を検証する。
この関数は blob、カレンダー正本、鍵、インスタンス設定をコピーしない。
SQL だけの指紋一致をインスタンス全体のバックアップや復元の成功とは扱わない。
実 DB テストでは PostgreSQL 側の追加更新を含めて別の SQLite へ戻し、内容指紋の一致と
その後の採番を確認する。未知の制約・RLS・索引の拒否、コピー途中失敗の rollback、
source の不変性、Document 欠損、同一 DB への自己コピーも検証する。
#### 本番 PostgreSQL 移行の受入ゲート
今回の対象は、全 writer を停止した状態での SQLite→PostgreSQL の片方向インポートと、
移行後の通常運用である。PostgreSQL→SQLite の逆移行、自動切り戻し、二重書き込み、
オンライン差分同期は今回の実装・受入条件から除外する。
既存の core 往復テストは回帰テストとして残すが、本番全件の逆移行へ拡張する作業は行わない。
移行前バックアップと片方向インポートの整合性検証は引き続き必須とする。
2026-11-14 の棚卸しでは Store の SQL 呼び出し点は約 100 ファイル・967 か所ある。
これはすべてが SQLite 固有であるという意味ではないが、接続層と core だけでは
通常起動・認可・全アプリ機能を満たさない。次の未完了ゲートを残す。
2026-11-15 時点の受入条件は以下の 8 工程に整理する。1 と 2 の主要 DB 処理は共通テストを通過したが、
通常 HTTP/scheduler/CLI 経由の PostgreSQL 統合は工程 7 と合わせて検証する。
工程数は受入ゲートの区分であり、8 回の変更や応答で完了するという工数見積もりではない。
| 順序 | 残工程 | 本番切替前の受入条件 |
| --- | --- | --- |
| 1 | 認証と権限の統合 | 認証・公開・承認・ユーザー領域の DB 処理は移植済み。残る管理経路の直接 SQL、通常 HTTP 認証と navigation cache の PostgreSQL 統合を確認 |
| 2 | Domain と Campus と federation の統合 | namespace CRUD・管理者継承・token・instance・署名 manifest は移植済み。controller/managed プロセスの再起動、鍵・instance identity の保持と HTTP 配信を確認 |
| 3 | core と Document と City の接続 | 全 Store 変更系、GC pin、検証 I/O の予算、Document root identity、Asset 復元、Path 移動・削除時の City 境界・ACL・関連リンク・filename Revision・snapshot 検査・cache 失効を接続 |
| 4 | タスクと CalDAV と各拡張 | プロジェクト所属、VTODO、ETag/ctag/sync-token、通知、連絡先・RSS・ブログ等の repository と対応テーブルを移植 |
| 5 | ジョブと通知 | claim/lease/fencing、キャンセル、outbox 消費、重複排除、再起動時の処理、ログ保持を検証 |
| 6 | 検索と管理 | FTS5/rowid/PRAGMA/JSON 関数・照合順序への依存を分離し、権限付き検索・一覧と管理設定を検証 |
| 7 | 通常起動と設定 | backend 別 bootstrap、全 Ensure、secret 参照、schema 診断、readiness、CLI/standby の接続を統一し、PostgreSQL で全体試験を通過 |
| 8 | 全件インポートと切替 | 全正本テーブルの片方向インポート、再生成可能 cache の分類と再構築、canonical files・鍵の保持、件数・参照・内容指紋・採番の整合性、移行前 backup と PostgreSQL backup/restore を検証し、停止状態で本番切替 |
MySQL、S3、Redis、HA、逆移行はこの 8 工程の完了条件に追加しない。
#### 初回切替を短縮する場合の残件
初回は単一インスタンス・ローカル Document root・停止状態での片方向 import を対象とする。
利用者は必須残件を先行し、任意機能をリリース後へ回す方針を了承した。
Push 配信・zombie GC・ログの保持期限処理・hosted editor session には native 停止ゲートを実装した。
その他の機能を停止する場合も利用者へ制限を示したうえで、
起動時・HTTP・CLI・worker の全入口を同じ機能ゲートで拒否する。
`NewPostgreSQLWithDocumentRoot` で native の通常 Store を初期化し、
合成データによる Server 起動・HTTP 操作・停止後の再初期化まで接続した。
`cmd/pageswiki/main.go` は `PAGESWIKI_DB_BACKEND=postgresql` による選択と、
全件 import の完了記録・鍵・Document root の一致検査を接続した。未指定時は SQLite のままである。
全件転送は `pageswiki migrate-postgres` を使用する。
`internal/metadata/portability.go` の core 限定リハーサルとは別の実装である。
切替に直結する実装順序は次のとおりとする。
1. ジョブ基盤と outbox の統合。DB 層の claim・完了 token・再起動時の中断扱い・重複排除、
Task/Calendar/RSS のイベント登録は移植済み。Server の起動で worker owner を取得し、
停止と join 後に解放する。native 通常 Store による HTTP・再初期化・worker 二重起動拒否を検証済み。
2. 通常起動・検索・管理経路の接続。backend 明示の Store 初期化、主要画面、
内蔵エディタ保存、認証失効、DAV discovery まで接続済み。
本番用 backend 選択も接続済み。認証、ACL、公開範囲は省略しない。
3. 全件 import。全正本テーブル・鍵・設定・受付/操作履歴・同期番号を列挙し、
cache と区別して保全する。identity 採番、本文参照、件数・内容指紋と再実行を検証する。
4. 隔離した通常 HTTP 起動と再起動試験、backup/restore 検証後に停止移行する。
実行する機能の CRUD、DAV 条件付き更新、権限失効、失敗時の rollback を通してからリリースする。
| 後回しにできる候補 | 初回切替で必要な条件と制限 |
| --- | --- |
| HA/LB/DR、無停止・オンライン移行 | 単一インスタンス、旧系の writer を停止した import に限定。PostgreSQL の backup/restore は省略しない |
| PostgreSQL から SQLite への逆移行 | 既定どおり対象外。旧 backup からの復旧は、切替後の更新を引き継ぐ逆移行とは別物 |
| 自動 GC の同時実行と pin 機構 | native zombie GC は定期実行・手動 API・Store の全入口を拒否する。本文ファイルの GC を新設せず、容量を監視する。本文参照・hash の整合性検証は残す |
| 高度な全文検索・ランキング最適化 | native は権限付き Path/ファイル名検索と City メタデータ検索を実装。Page 本文・H1 の検索とサジェストへの H1 付与は未対応。FTS5 や全本文走査で代用しない |
| hosted editor | native は起動・ticket 交換・session 取得・保存を拒否し、選択肢から除外する。設定と既存 session は保全し、内蔵エディタを使用する。session の base revision 更新と本文保存をまたぐ整合性は後続対応 |
| サムネイル再生成・リソース履歴のグラフ | 対象イベントと API を明示的に無効化。正本と派生 cache/履歴の分類を先に確定し、未分類テーブルを捨てない |
| Push/SMTP/外部サービスへの送信 | 配信だけを停止する制限運用は可能だが、Inbox と受付履歴は保持する。不明な送信結果を成功や再送待ちへ変換しない |
| ログの自動保持期限処理 | native では定期 cleanup を実行せず、手動呼び出しも拒否する。ログと集計を保全する代わりに容量監視が必要。policy 別の件数・実行時間を制限した cleanup は後続対応 |
| MySQL、S3、Redis 等の追加 backend | 今回の PostgreSQL 切替とは別プロジェクトとして扱う |
全件 import、通常起動、認証/公開権限、正本ファイルと鍵の保全、必要機能の統合試験、
移行前 backup は短縮対象にしない。機能縮小で省けるのは各機能の稼働対応であり、
その機能が持つユーザーデータの保全ではない。
#### ジョブと HTTP 接続の移植状況
`store-event-jobs` は PostgreSQL 用の独立 migration とし、定義、キュー、ログ、集計と設定を作成する。
native worker は専用接続の advisory lock により同一 DB/schema に一つだけ起動できる。
これは単一インスタンス用の排他であり、HA の lease/failover を提供するものではない。
接続が利用不能なら新規 claim を拒否する。
`Server.NewChecked` は worker owner 取得・イベント登録の失敗を起動エラーとして返す。
`Runner.Stop` は受付を止めて実行中処理を cancel し、完了状態保存を待つ。
`Server.Close` は scheduler loop・保守処理・worker の終了後に排他を解放する。
停止待ちの timeout は終了完了を意味せず、実行中処理が残る間は排他を保持する。
main の SIGTERM/Ctrl+C は Campus 同期の新規開始を止め、進行中同期の終了を待ち、
HTTP と worker の停止へ接続した。各外部同期要求は従来の network timeout を使う。
ジョブの claim、同時実行数とキュー深さの検査、再試行は writer transaction 内で行う。
完了には claim ごとの token を要求し、再試行・再起動前の worker の完了を拒否する。
完了状態の保存後にログ保存が失敗しても、副作用のあるジョブを自動で再実行しない。
再起動時に残る running は結果不明として failed にし、明示的な再試行を待つ。
schema 初期化だけで稼働中のジョブを奪わない。
定期イベントの enqueue と次回日時の更新は同一 transaction で行い、キュー満杯なら両方を rollback する。
組み込みイベントの登録は管理者による無効化や周期変更を上書きしない。
Task の活動通知、期限通知、Focus、日次メール、RSS、Calendar sweep の登録を接続した。
外部配信の実行可否は別の制限であり、登録の移植完了をもって配信を有効化しない。
outbox の正本 journal と型別 watermark は core 所有のままとし、
`store-activity-consumers` が通知先ごとの checkpoint と検索 index を追加する。
型別に件数を制限して読み込み、別 consumer の処理済み状態に影響されず、
checkpoint の更新は単調増加とする。投影処理と同一 transaction で rollback できる API を維持する。
HTTP に残っていた Object alias、Calendar の active member、City zone kind、ブログ射影先、
設定変更対象の Campus 解決、個人表示設定の直接 SQL は Store API に移した。
参照は件数/時間を制限し、alias と射影先の権限判定は引き続き HTTP 側で行う。
管理対象を解決できない場合は現在の Campus へ fallback せず拒否する。
個人表示設定は現在の membership を再検査し、CAS と read-only 拒否を適用する。
`EnsureTasksSchema` は native foundation と productivity migration へ接続した。
アナウンス、プレビュー解析 cache、リソース履歴も native migration と Store API に接続した。
アナウンスは Domain を跨いだ同一 UUID の上書きを拒否し、削除時は Inbox との transaction を維持する。
プレビュー解析 cache は PostgreSQL の byte 長で容量を制限し、resource sample は job UUID で重複排除する。
これらの変更は起動依存の移植であり、新しい表示機能の追加ではない。
Push は鍵・購読・配送状態を保持する schema のみ作成し、Inbox INSERT trigger は設置しない。
Store の登録・claim・完了・cleanup、HTTP、キー生成、配信の入口で拒否する。
native 定期 enqueue と claim は Push を除外し、既存定義の日時や不明な配送状態を書き換えない。
停止されたログの期限処理と zombie GC も、機能設定の変更で再有効化できない backend 制限とする。
HTTP 検索の SQLite 直接生成を Store 経由に変更し、native では Path と元ファイル名を検索する。
最新 revision の MIME/拡張子/更新日時、Object 作成日時による絞り込みを候補 LIMIT 前に適用する。
候補は最大 1,000 件、返却は最大 200 件、SQL と権限判定の予算は 2 秒とし、
本文ファイル・legacy body 列を検索やタイトル補完のために走査しない。
候補 cursor を閉じてから権限判定するため、1 接続の pool でも権限問い合わせを実行できる。
検索・サジェスト HTTP の `X-PagesWiki-Search-Profile: metadata-only` はこの制限を表す。
対象範囲に候補が 1,000 件を超える場合、候補制限による取りこぼしはあり得る。
City 検索は native の read snapshot 内で種類ごと最大 1,000 件のメタデータを集め、
transaction を閉じてから Quartier・Street を含む親階層の権限を確認する。
Domain/Path 境界、日付条件、未定義 Spot の Street へのリンクを維持する。
Page のファイル種別指定時には City 要素を混ぜない。
hosted editor は `store-adapter-sessions` に ticket/session/base revision を保全する。
native では Store と HTTP の操作入口を拒否し、アダプタ選択肢から editor plugin を除外する。
閲覧用 plugin と内蔵エディタはこの制限の対象外である。
既定 editor の設定を削除したり、残存 ticket を期限切れ cleanup で消したりしない。
この検索・保全ガードは合成データの PostgreSQL 17 と SQLite で検証した。
`go test ./...`、対象の race 検査、`go vet ./...`、`cmd/pageswiki` のビルドを通過した。
検索検査には 1 接続での権限問い合わせ、Domain・親階層の拒否、文字列のリテラル一致、
1,100 件の候補に対する LIMIT 前の絞り込み、過去 revision の除外、cancel を含む。
検索の repository 統合検証とは別に、次の通常 HTTP 起動検証を行う。
`NewPostgreSQLWithDocumentRoot` は鍵と Document root を先に検査し、native schema を依存順に初期化する。
欠落・不正な `auth.key` を生成し直さず、`PAGESWIKI_AUTH_KEY` を指定しない場合は既存の 32 byte 鍵を要求する。
Campus/Domain 未配置、所有 Campus が存在しない Domain、Domain が存在しない Path は起動を拒否する。
既存の無効 Campus を既定 Campus へ付け替えず、SQLite の legacy body backfill も実行しない。
`BackfillDocuments` の native 呼び出しは明示的に拒否する。
正本ファイル全件の hash 照合は import/restore 工程の責務であり、この constructor だけでは保証しない。
合成データの PostgreSQL 17 で通常 Store と `Server.NewChecked` を組み合わせ、
実 HTTP listener の本文取得、主要画面と管理パネル、内蔵エディタ保存と競合 409、
無効・失効セッションの 401、CalDAV/Task DAV/CardDAV の discovery を検証した。
同じ DB と Document root で Server を停止・再初期化し、本文と認証 session の継続を確認する。
稼働中の別 worker 起動は拒否し、停止完了後に再取得できる。
resource event の保存は同じ job UUID で再実行しても重複しない。
管理画面の最近の Object は native query に分岐し、Domain 内の代表 Path と最新 revision のみを扱う。
返却上限 200 件・SQL 予算 2 秒とし、Page 本文は読み込まない。
全件 import と内容照合、本番 backend 選択、合成データの PostgreSQL dump/restore は接続した。
停止切替のコマンドと制限は [PostgreSQL 移行手順](../operations/postgresql-migration.md) にまとめる。
本番切替には、移行前の一貫したバックアップと、そのインスタンスの schema preflight・全件 import の成功が必要である。
合成データの試験通過は、本番データの移行完了を意味しない。
`application_import_catalog.go` は保全対象と SQLite 専用索引・migration ledger の列を固定する。
未知のテーブル・列・trigger/view 定義を検出したら拒否し、cache と推測して捨てない。
移行先に既存データがある場合は schema 準備の前に拒否する。
データ転送は単一 transaction とし、schema が用意した既定行のみを置換する。
一時停止するのは派生状態を更新する user trigger だけで、FK・CHECK・UNIQUE は維持する。
各テーブルの型付き内容指紋・件数、Document の SHA-256、namespace の参照を照合する。
SQLite の削除済み最大採番も保持し、transactional identity restart で番号の再利用を防ぐ。
タスク DAV の内部索引キーと削除 tombstone は NUL 区切りから native v1 base64url 形式に変換する。
この変換を report に明示し、正本 JSON とクライアントに公開する href は変更しない。
失敗時の全件 rollback、修正後の再試行、重複 import 拒否、認証 session・画像・日本語タグ、
プロジェクト別タスク・連絡先 sync-token の継続を合成データで検証する。
同じ正本ファイルを保持した schema 単位の `pg_dump`/`pg_restore` 後も本文・認証・DAV を検証する。
#### 次の実装単位と検証状況
工程 3 の通常保存・履歴取得・復元は Store 境界へ接続済みである。
エディタ保存 API は Domain と期待 HEAD を明示し、PostgreSQL 分岐から本文永続化・参照固定・
Revision・outbox を一つの契約で扱う。SQLite は既存保存動作を維持する。
PostgreSQL の通常 HTTP 経路では保存と期待 HEAD 競合を確認済み。
履歴復元を含む残る操作の HTTP 確認は工程 7 に残る。
`path_mutation.go`/`path_snapshot.go` の通常操作、`city_operations.go`/`city_organize.go`、
City map 読み取りと Asset Store API は移植済みである。
`city.go` の個別作成・削除・relation、`city_plan.go` の一括変更計画、ページ一覧と
アーカイブ import 管理も移植済みである。City の作成・配置・再帰削除と計画適用は
共通 namespace lock の中で topology version と監査イベントを更新し、途中の SQL 失敗は rollback する。
`EnsureCitySchema` は native schema と公開制御の migration へ接続した。
自動生成の候補取得と名前判定は Store API に集約し、候補 cursor を閉じてから階層を解決する。
同じ境界の解決結果は一回の plan 構築中に再利用し、DB 故障を「既存要素なし」として扱わない。
候補は 20,000 件を上限とし、超過時に途中までの City を適用しない。
定期・編集イベントからの実行は scheduler 移植と統合して検証する。
children は Domain 全件を Go へ読み込まず、対象 subtree から直下要素を SQL で抽出する。
DB generation とプロセス内の cache epoch で別 Store の変更・取得中の失効に追従する。
Browser と children の列挙上限は 20,000 件、問い合わせは timeout 付きとし、超過を明示する。
PostgreSQL の Browser title は本文 cache ではなく canonical HTML の先頭 64 KiB から取得する。
一回の title 読み取りは 32 MiB と timeout で制限するが、DocumentSize の個別 I/O は残る。
権限付き Object metadata 一覧は既存の候補・alias 上限と継続 cursor を維持する。
アーカイブ import は独立 migration `store-imports` でセッション、計画、journal を作成する。
Path rollback とセッション状態更新は一つの transaction とし、import 時と Object が一致する
binding だけを削除する。City cleanup はそれに先行する再試行可能な別フェーズであり、
City と Path を一括 rollback する transaction ではない。
旧 worker の void 状態更新 API は失敗を呼び出し元へ返せないため、scheduler 移植時に
エラー伝播・状態遷移・再試行を併せて整理する。
工程 3 の残件は
`domain_paths.go` 等の legacy schema adoption と bootstrap の分離、残る直接 SQL writer の棚卸し、
import worker のエラー伝播、Path 変更を消費するイベント処理との統合である。
同時 GC の pin、Document root identity、巨大 payload 検証の I/O 予算も起動前のゲートとして残す。
すべての Path/Revision writer の同じ排他契約への接続が済むまで PostgreSQL の通常起動は許可しない。
工程 4 は task/CalDAV、calendar、contacts/CardDAV、feeds、periodicals の順に
保存スキーマ・変更処理・一覧・ETag/同期 token を一組ずつ移植する。
タスクやカレンダーの処理を停止して起動検証だけを通す方式は採用しない。
工程 5 と 6 の job claim、notification、全文検索も同様に機能契約を保つ。
タスク本体は `store-tasks-foundation` の native 空 DB schema と Store 操作を追加した。
保存・削除・DAV 設定更新は権限の再確認前に共通 namespace lock を取得する。
task head、履歴、変更 journal、outbox、DAV index、通知予約、達成度 index は
一つの保存 transaction に含める。削除は tombstone を残し、Wiki とカレンダーを削除しない。
一覧では JSON 抽出、文字列検索、パラメータ番号、階層 cursor の真偽値を backend 別に扱う。
SQLite の DAV 内部索引は NUL 区切りを含むが、PostgreSQL の TEXT は NUL を格納できない。
native 内部キーは `v1:{base64url(project)}:{base64url(value)}` とし、既定 collection も同じ方式にする。
外部 URI・resource 名・UID・canonical JSON は変更しない。全件 import では derived DAV index を
canonical head から再構築し、削除 tombstone の `dav_name`/`dav_uid` も旧 NUL 形式から変換する。
この変換なしに SQLite の該当列をそのままコピーしてはならない。
個人既定値、作業時間、Pomodoro、日次集計、ダッシュボードと予定枠の DB 予約は移植済みである。
設定と配置の version を独立させ、作業時間の訂正・取消は監査履歴と同時に commit する。
writer は権限確認前に共通 namespace lock を取り、対話的な更新は 5 秒で timeout する。
`store-task-productivity` の追加 migration で Focus span と予定枠の title を導入し、
既存の `store-tasks-foundation` migration は変更しない。
`store-notification-inbox` は Inbox のみを作成する。通知挿入は一意キーの競合を
transaction 内で処理し、別プロセスからの重複要求も同じ UUID を返す。
タイマー完了・期限/着手日の通知は、Inbox 挿入と元の状態更新を同じ transaction に含める。
通知保存が失敗した場合は元の状態も rollback し、次回に再試行できる。
活動 journal の補完は既存 outbox の冪等キーを再利用する。
配信候補は最大 100 件・3 秒に制限し、読めなくなった所属先の情報を通知へ複製しない。
タスク capture/Wiki 同時作成と再作成、プロジェクト配下のメモ作成は移植済みである。
native では Object の作成元 Domain と primary Path を明示し、本文は canonical Document に置く。
Task・受付記録・Object・Path・Revision・outbox は同じ transaction で commit する。
入力本文は HTML とマクロをエスケープし、削除後の明示的再作成でも既存の Wiki 本文を変更しない。
受付記録だけ残っている不整合は自動復活させず、修復が必要なエラーとして扱う。
メールダイジェストの claim・送信履歴・明示的再試行も移植済みである。
共通 namespace lock と状態条件で scheduled/manual claim を一意にし、同意・設定 version・
所属権限を再確認する。送信結果が不明な試行は自動再送せず、本人の重複送信了承を必要とする。
90 日経過で詳細履歴を削除しても、日次予約と再試行の受付記録は重複防止のため保持する。
保守処理は 3 秒・中断判定 100 件・履歴削除 500 件に制限する。
カレンダーは `calendar-cache` migration で PostgreSQL の月別/イベント索引を作成する。
正本は従来どおり月別 ICS と `calendar.json` の manifest であり、DB には移さない。
明示的な backend 選択を HTTP の Repository 初期化へ接続し、予約済みタスク予定枠の
正本作成・移動後の再試行と日次予定の cache projection を検証する。
manifest 更新後の索引再構築失敗は transaction を rollback し、次回アクセスで修復する。
cache 更新は 30 秒で打ち切る。全 writer は同じ正本 root と有効な flock を共有する必要があり、
独立した filesystem を持つ replica 間の HA は未対応である。
任意の DAV filename を UID として復号する際は UTF-8 と制御文字を検証し、
非テキストの復号結果を PostgreSQL の TEXT パラメータへ渡さない。
連絡先は `store-contacts` migration で native schema と変更 journal の trigger を導入する。
vCard 正本・履歴 hash・任意 resource 名・tombstone を維持し、更新と変更番号を同時 commit する。
CardDAV の inventory と sync-token は PostgreSQL の REPEATABLE READ で同じ snapshot から取得する。
metadata inventory は vCard 本文を返さず、UTF-8 の byte 長を返す。
保存と snapshot 取得は 5 秒で timeout し、保存は権限・資格情報確認前に共通 namespace lock を取る。
全 DB import 時は contact epoch と変更番号を保全し、identity sequence を最大値に合わせる。
ブログ・日記は `store-domain-entry` の設定 schema を再利用し、追加の `store-periodicals`
migration で記事索引・変更履歴・投稿受付記録・射影設定を作成する。
書き込みは権限確認前に共通 namespace lock を取得する。記事新規作成では Object・primary Path・
Revision・埋め込み参照・受付記録・記事 metadata・変更履歴・outbox を同じ transaction で確定する。
本文は canonical Document に保存し、Asset 名は当該 Domain の HEAD を不変 hash に解決して保持する。
記事の登録解除は索引だけを削除し、Page 自体は残す。再登録は変更履歴から version を継続する。
公開タイトルの問い合わせは許可済み navigation の UUID と Domain に限定し、入力件数も予算内に制限する。
射影は同じ Campus の有効な local Domain 同士に限り、多段射影・循環と無効な配信元を拒否する。
全件 import では投稿受付記録と記事変更履歴も正本として保全し、履歴の identity 採番を復元する。
RSS は `store-feeds` migration で購読元・記事 cache・ローカル既読状態・取り込み受付と
FreshRSS の明示的操作 receipt を保持する。書き込みは namespace lock 取得後に
native actor と拡張設定を検証する。読み取りは 3 秒、書き込みは 5 秒で制限する。
FreshRSS 分類は PostgreSQL の JSONB 関数で検索し、カテゴリなしの null/空配列を扱う。
壊れた拡張設定は当該 Domain を処理対象から外し、他の購読元の候補検索を中断させない。
送信結果が不明な操作は購読元の変更・削除後も履歴として保持し、自動再送しない。
期限切れ claim の回収は 1 transaction あたり 100 件・3 秒に制限する。
次の実装単位は scheduler の native schema と claim/lease/ログ保持、各イベント登録である。
Push 配信と scheduler のイベント登録・実行は未統合である。
外部カレンダーの内容は検証に用いない。
`EnsureTasksSchema` と `EnsureNotificationSchema` の native 通常起動は引き続き未対応として拒否する。
旧 free helper を使う未移植の呼び出し元は SQLite 用であり、native Store の receiver へ順次接続する。
DAV HTTP の discovery/REPORT/条件付き PUT/DELETE、ETag・ctag の再起動後整合性と
カレンダー共通 endpoint の実機統合も残る。task payload 永続化中に writer transaction を保持する
既存動作と GC pin は、Document の I/O 予算・参照固定の残件として扱う。
2026-11-15 の合成データによる検証では、SQLite とローカル PostgreSQL 17 を使った
全 Go テスト、移植済み Store の共通契約・PostgreSQL migration テストの race 検出、
`go vet ./...`、ローカルバイナリ生成が成功した。
公開・承認、ユーザー領域・電話番号の同意、Domain 同時作成・移動、管理者継承の取消、
Federation の token 失効・署名改ざん・replay・同時初回受信・checkpoint 故障時の rollback を含む。
通常保存の追加試験では別 Store からの同時 CAS と無条件 append、言語別履歴、
create/save/bind の origin 制約、別 Domain への移動後の拒否、現在の Asset HEAD を変更した後の
履歴復元、本文・埋め込み payload の欠損、Page/Revision の outbox 故障時の rollback を確認する。
Path/City/Asset の追加共通試験では、再帰移動・コピー・重複選択の削除、literal な `%`/`_`、
stale snapshot の拒否、保護 namespace の拒否、コピーと filename Revision の参照保持、
navigator の移動先重複解消、Spot 統合後の所属と URL 保持、同時 topology version 更新、
Asset の同時 CAS・履歴復元・欠損拒否・監査保存故障時の rollback を確認する。
City CRUD・一覧・アーカイブ import の追加試験では、stale plan、再帰削除中の監査故障、
archived 名の再利用、literal prefix、12 件以上の指定順序、canonical H1、metadata cursor の
重複防止、別 Store からの cache 失効、import 番号重複時の計画保持、Domain 分離、
Path rollback と状態更新の原子性、付け替え済み Path の保護、read-only 拒否を確認する。
タスクの追加試験では、プロジェクト別の同一 DAV UID、同一 collection 内の衝突拒否、
既定 collection の分離、親子階層、日付・優先度・添付の絞り込みと pagination、履歴、
完了時の通知予約削除、削除の再試行と復活拒否、DAV 資格情報の発行・失効を確認する。
PostgreSQL の別 Store からの同時保存は一方だけ成功し、outbox 故障では保存と削除が rollback する。
readonly Principal の書き込み拒否と、Membership 失効後の読み取り拒否も確認する。
生産性機能の共通試験では、個人設定と配置の独立した CAS、作業時間の訂正・取消・履歴の
pagination、Pomodoro の停止区間を除いた集計、完了通知の一度だけの登録、予定枠の状態変更、
期限通知の再送防止と活動 journal の重複排除を確認する。
PostgreSQL では別 Store の同時設定更新・作業開始・タイマー開始・完了処理も試験し、
監査失敗時に作業時間/Focus span が途中で更新されないこと、Inbox 故障後の再試行、
同時通知挿入の一意性、受信者 scope と失効後の拒否を確認する。
capture/メモの共通試験では日本語 Path と本文、HTML/マクロの無害化、受付の再送、
同一 Path の衝突拒否、削除後の明示的再作成と本文保持、stale project の拒否を確認する。
PostgreSQL では受付記録の故障による全関連 metadata の rollback、別 Store からの同時 capture、
canonical 本文の読み戻し、作成元 Domain・primary Path・cache generation を確認する。
メール管理の共通試験では日次 claim の重複拒否、重複送信了承・受付再送・履歴 pagination、
同意変更後の取消、保持期限後の予約・受付保持を確認する。PostgreSQL では複数 Store の
scheduled/manual claim と、送信結果保存失敗時の rollback、中断試行の自動再送防止を確認する。
カレンダーの共通試験では月またぎ移動、ETag 競合、DAV filename 保持、既定 calendar、
共同編集者の読み取り権限と失効、全 cache 消去後の再構築、削除を確認する。
PostgreSQL では別 Repository の同時編集、再構築・削除の DB 故障時の正本保持と再試行を検証する。
タスク予定枠の再送が移動済み予定を上書きしないこと、日次 projection が現在の時刻を返すこと、
外部 source は snapshot 読み込み前に拒否されることも合成 metadata で確認する。
連絡先の共通試験では日本語検索、未知の vCard property 保持、同一 UID import の再送、
削除の差分配信、履歴復元、metadata の byte 長、差分 pagination、資格情報失効を確認する。
PostgreSQL では同時 CAS と履歴保存故障時の連絡先・同期番号の rollback を確認する。
ブログ・日記の共通試験では日本語記事の作成・再送、変更された再送入力の拒否、
記事 metadata の CAS、登録解除後の Page 保持と再登録、Asset HEAD 更新後の本文参照固定、
欠損 Asset の拒否、公開タイトルの Domain 分離と件数上限、射影の循環・無効な配信元の拒否を確認する。
PostgreSQL では変更履歴の保存故障時に Path と受付記録が rollback すること、
別 Store からの同時投稿要求が一つの記事となること、Campus 無効化後の投稿拒否を確認する。
RSS の共通試験では日本語・literal 検索、日時 cursor、既読状態の CAS、
FreshRSS のカテゴリ/未分類/空フォルダ、購読 import と Wiki 取り込みの再送、
削除済み購読元の復活拒否、外部操作の確認・期限切れ・読み取り専用再確認を検証する。
購読元を変更・削除しても不明な外部操作を保持し、履歴の metadata 欠損を許容する。
PostgreSQL では複数 Store の同時 claim、cache 保存故障時の lease rollback、
100 件ずつの期限切れ回収、破損設定と Campus 無効化後の拒否を確認する。
ジョブの共通試験では claim・完了・再試行・キャンセル・一覧・ログ・集計と read-only 拒否を確認する。
PostgreSQL では同時定期登録の一意性、同時 claim の上限、二つ目の worker owner の拒否、
再起動後の結果不明ジョブの保留、古い完了 token の拒否、完了ログ故障時の状態保持を確認する。
outbox は型別・Domain 別の取得、consumer の独立性、同時 checkpoint の単調性、
rollback と read-only 拒否を両 backend で検証する。
HTTP 用 lookup と個人表示設定の共通試験では Domain 分離、無効 Principal、対象欠損時の拒否、
設定 CAS を確認する。scheduler/outbox/lookup の対象テストは race detector でも検証する。
これらは component テストであり、PostgreSQL を指定した通常アプリ起動や本番データ import の成功ではない。
検証は `GOPROXY=off GOSUMDB=off` とし、実 PostgreSQL の共通テストには
`PAGESWIKI_TEST_POSTGRES_DSN` で使い捨て DB を指定する。各テストは専用 schema を作成・削除するため、
本番 DB を指定してはならない。実際の外部カレンダー、OIDC/LDAP/SMTP、Gitea へのアクセスは不要。
2026-11-15 に Gitea の復旧連絡を受領した。移植中は引き続きローカルビルドで検証し、
全 repository・通常起動・インポートのリリースゲートを満たした後に、commit/push、
SemVer タグ、Gitea CI の image build とリリースへ進む。復旧だけを理由に未完の移植を配布しない。
ローカルビルドの成功は DB 切替の許可条件ではなく、上記ゲートと停止状態の全件インポート検証を
満たした後、移行前 backup を確保し、同じ成果物で隔離起動試験を経て本番を起動する。
未対応機能を暗黙に初期化したり、読めないテーブルを cache とみなして捨てたりしない。
外部 RDB 障害時に SQLite へ自動 fallback する設定は作らず、二つの DB が別々に
更新を受ける状態を防ぐ。最低 PostgreSQL 対応版と CI matrix の確定も切替条件とする。
#### 片方向インポートと切替の設計
本番切替は全ゲートが通った後、次の順で行う。全件移行ツールは
`pageswiki migrate-postgres` であり、core リハーサルをその代用にしない。
1. HTTP/CalDAV/CLI、scheduler、federation を含めた全 writer と GC を停止し、保守状態を確認する。
2. SQLite の整合した snapshot、Document、カレンダー正本、設定・鍵・instance identity を保全し、復元検証する。
3. 空の専用 PostgreSQL へ全件移行し、件数・内容指紋・参照・採番・payload を照合する。
4. 読み取り検証でログイン、権限、公開ナビゲーション、検索、タスク/CalDAV、管理・配信を確認する。
5. 反映する全プロセスを一斉に PostgreSQL 側へ向け、旧 SQLite は凍結したまま、書き込み再開時点を記録する。
書き込み再開前にインポートや検証が失敗した場合は移行を中止し、元の SQLite を維持する。
書き込み再開後は PostgreSQL を正本とし、障害時は PostgreSQL 側の復旧・修正を基本とする。
移行後の更新を SQLite に反映する機能は今回提供せず、接続先を旧 SQLite へ自動で戻さない。
この制約を運用手順にも明記し、逆移行の完成を本番切替の前提条件にはしない。
### S3:運用と移行
- [ ] 編集可能な設定例と薄い backup / release / deploy script。
- [ ] DB/Document/calendar/keys を束ねる backup manifest、pin、verify、restore rehearsal。
- [ ] 共通 online CLI、portable bundle export/import、plan/apply/retry。
- [ ] Web バックアップ管理、初回ようこそ画面、ジョブ状態とリソース監視の接続。
完了条件は接続成功だけではなく、機能契約・故障注入・再起動・データ移行・
バックアップからの復旧試験まで通ること。未実装 backend を「対応済み」と表示しない。
## 12. 根拠資料
- [SQLite WAL:network filesystem の制約](https://sqlite.org/wal.html)
- [PostgreSQL の transaction-level advisory lock](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)
- [PostgreSQL の identity 変更](https://www.postgresql.org/docs/current/sql-altertable.html)
- [PostgreSQL の RESTART と transaction](https://www.postgresql.org/docs/current/sql-altersequence.html)
- [pgx の database/sql 接続](https://pkg.go.dev/github.com/jackc/pgx/v5/stdlib)
- [S3 の conditional writes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html)
- [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/)
- [PostgreSQL backup / restore](https://www.postgresql.org/docs/current/backup.html)
- [MySQL 8.4 backup / recovery](https://dev.mysql.com/doc/refman/8.4/en/backup-and-recovery.html)