Files
pages/docs/design/ja/component-names.md

217 lines
18 KiB
Markdown

# PagesWiki のコンポーネント命名と責務
2026-11-01 採用。神名を実装アーキテクチャの部品名として使用する。
Grammaratur、Dregarnuhr、Geduldh、Mestionora、Ordoschnellic、Schutzaria、Kunstzeal、Seheweit の
8部品の初期分離を実装した。初期分離と各部品の後続機能・本番展開の完了は区別する。
## 由来と適用範囲
プロジェクト名 pages は、作者の意図として Little Glee Monster の楽曲 pages に由来する。
Knowledge City Model は『とある科学の超電磁砲』の学舎の園に着想を得た知識の配置モデル。
このモデルの Campus、Domain、Quartier、Street、Spot、Page は変更しない。
内部の機能分担には『本好きの下剋上』の神々の名前を用いる。
作品の役割とソフトウェアの役割を重ねる命名の参考は
[TOMOYO Linux 作者の説明](https://i-love.sakura.ne.jp/tomoyo/)。
名前の参照表は [プロジェクト作者の Gist](https://gist.github.com/anya-tokugawa/d3939b16298937f8b7e39a6ec3595464)。
以下の英字表記は PagesWiki 内の採用表記であり、作品の公式翻訳表記を定義するものではない。
## 採用した部品名
| 部品名 | 内部識別名 | 担当範囲 | 担当しないもの |
| --- | --- | --- | --- |
| Mestionora メスティオノーラ | `mestionora` | 索引、検索、知識間の関連性の解決 | 正本保存、認可の独自判断、編集UI |
| Grammaratur グラマラトゥーア | `grammaratur` | 文書形式変換、変換時の情報保全、変換診断 | 認可、画面用sanitizer、macro展開、Revision保存 |
| Geduldh ゲドゥルリーヒ | `geduldh` | 内容アドレス付きDocumentの保存・取得・完全性検証 | 認証やタスク等の全DB、参照なしを独断判定するGC |
| Dregarnuhr ドレッファングーア | `dregarnuhr` | 実行時刻、ジョブ投入・実行制御、リース、再試行 | カレンダーやタスクの業務ルール、通知本文・宛先 |
| Ordoschnellic オルドシュネーリ | `ordoschnellic` | イベントに応じた通知、宛先別配送、配送状態 | 業務変更の生成、正本トランザクションの所有 |
| Schutzaria シュツェーリア | `schutzaria` | 権限評価、公開範囲、共有・承認ポリシーの評価 | 個々のOIDC/LDAPプロバイダー実装、表示用HTML変換 |
| Kunstzeal キュントズィール | `kunstzeal` | 図・スライド等の描画プロバイダー実行基盤 | 独自描画エンジンの強制、文書正本の変更 |
| Seheweit ゼーエヴァイト | `seheweit` | リソース・稼働状態の収集、集約、観測 | ジョブ制御や観測対象の業務処理 |
名前はリリースごとに変えず、責務と共に維持する。バージョンは従来の SemVer 2.0.0 を継続する。
機能を増やすためだけに神名を追加せず、境界と受入条件が成立してから部品を作る。
神々の系譜や関係を依存グラフ、権限の上下関係、配置単位へ強制的に写さない。
## 実装と運用の命名規則
- パッケージ名は小文字の内部識別名、設計上の部品名は先頭大文字の表記とする。
`DocumentStore` 等の契約・インターフェースと `PutIfAbsent` 等の操作名は技術用語を使う。
- 1部品は1コンテナを意味しない。プロセス内のパッケージとして分離でき、独立配置は別判断。
- UIは検索、通知、権限設定などの通常名を維持する。神名の理解を利用条件にしない。
管理者向けの診断や設計文書には、神名と一般的な役割名を併記できる。
- URI、既存のprovider/extension ID、設定キー、DB名、保存形式、イベント型、consumer ID、
レジストリ上のイメージ名を命名のためだけに変更しない。特にconsumer IDの改名で
既存checkpointを失い、通知や処理を再実行することを防ぐ。
- 新たなログ・トレースで識別が必要なら固定の `component=grammaratur` 等を用いる。
文書本文や認証情報は記録しない。無条件に変換ごとのログを追加しない。
- 既存の `server` / `store` 一式を神名へ置換しない。呼び出し契約・テストを確立してから
部品を抽出し、移行中は一方向の互換ラッパーを残す。実装を二重に保守しない。
## Grammaratur の実装契約
初期実装は `internal/grammaratur`。HTTP、DB、ファイル、ネットワークへ直接アクセスせず、
文字列の変換だけを行う。認可と入力サイズ上限は呼び出し元が検証する。
| 関数 | 契約 |
| --- | --- |
| `HTMLToMarkdown` | 従来の通常変換。保護フェンスを理解しない外部エディタ等にも渡せる。変換損失の可能性は従来どおり |
| `MarkdownToHTML` | 従来のMarkdown方言とオプションを維持した通常変換 |
| `HTMLToMarkdownAuthoring` | 往復変換で構造・属性・文字が変わる場合は元HTMLを保護ブロックに保持 |
| `MarkdownAuthoringHTML` | 明示的にauthoringを選んだ呼び出しだけで `{=html}` ブロックをHTMLへ戻す |
出力は表示を許可されたHTMLではない。ブラウザー表示時は従来どおり認可・macro展開・
sanitizer・CSPを適用する。原文の保全とスクリプトの実行許可を混同しない。
通常変換を保護ブロック対応へ暗黙に切り替えず、hosted editor の保存形式も変更しない。
`internal/compiler` のHTML/Markdown変換関数と `render.Markdown` は Grammaratur へ委譲する。
組み込みエディタ、authoring API、Markdown出力、hosted editor のHTML入力変換は
Grammaratur を直接呼び出す。既存の通常Markdown呼び出しは `render.Markdown` 経由でも
同じ実装を使う。図のhash等、文書形式変換以外の `compiler` の処理は今回移さない。
依存方向は呼び出し元 → Grammaratur → 変換ライブラリ。
Grammaratur から server/store/db/render/compiler へ戻る依存は作らない。
新たな形式や詳細診断を追加する場合も、この境界を維持する。
## 移行順序と受入条件
1. **Grammaratur 初期分離**:通常変換と保護変換を集約。既存の関数・API・返却形式を維持。
通常変換の旧ライブラリ出力との一致、互換ラッパー、保護ブロック、エディタ、
hosted editor、表示安全性、ドキュメントexportを検証する。
2. **Dregarnuhr 初期分離**:現行schedulerから汎用の時刻・retry・dispatch契約を抽出。
preview、City、calendar、taskの実行ハンドラーは登録型の利用者として残す。
fake clockとworker競合試験で優先度・実行上限・既存claimを検証する。
期限付きlease・fencingは既存実装にもなく、初期分離には含めない。
[実装契約と後続TODO](dregarnuhr.md) を参照。
3. **Geduldh 初期分離**:既存 `documentstore.Store` 契約をaliasで維持し、
ローカル保存と検証付き一時展開の実装を `internal/geduldh` に分離。
filesystem layout、hash、Range、streaming、移行・DR手順を変えない。
大きな `store` パッケージ全体の改名はしない。[文書保存契約と残件](geduldh.md) を参照。
4. **Mestionora 初期分離**:SQLite検索・索引・City検索を分離し、
呼出し元の権限判定と既存の候補・抜粋予算を維持。[検索と索引契約](mestionora.md) を参照。
5. **Ordoschnellic 初期分離**:Web Pushの有界配送・再試行・暗号化を抽出し、
Inboxの原子的登録と購読checkpointを維持。再送が起こり得る既存の保証範囲を変更しない。
[通知配送契約と残件](ordoschnellic.md) を参照。
6. **Schutzaria 初期分離**:DB非依存の読み取り・Locality・グループ・公開範囲・承認状態評価を分離。
認証・DB読込・公開確定transactionは既存側に残す。[権限評価契約と残件](schutzaria.md) を参照。
7. **Kunstzeal 初期分離**:ビルトイン表示方式の選択、Krokiの有界描画、図hash/cacheを分離。
認可・ソース由来・CSPを維持し、redirect拒否とcache原子的置換を追加。[描画契約と残件](kunstzeal.md) を参照。
8. **Seheweit 初期分離**:リソース収集と履歴保持・bucket規則を分離。現在値APIと背景監視を接続し、
収集読込上限・容量計算・取消/read-only保存を補強。認可とSQLは既存側に残す。[観測契約と残件](seheweit.md) を参照。
この移行は配置変更、DB migration、機能追加を必須にしない。各段階でソース変更、
テスト、commit、CI、デプロイを別々に記録する。本番反映は検証後の別操作とする。
## 今回の変更範囲
- 採用済み:8部品の名称と責務、互換性と依存方向の規則。
- 実装済み:8部品の初期分離、旧入口の委譲、利用側の接続、境界・互換性テスト。
- 後続:Dregarnuhr のリース・fencing・終了処理、
Grammaratur の形式追加・詳細診断・ブロック単位の保護、Geduldh の外部backend・配置分離、
Mestionora のポリシー事前読込・現行専用索引・言語別検索、Ordoschnellic のclaim世代・購読更新競合・配送観測、
Schutzaria の権限読込の一貫性・承認継承・権限総覧、Kunstzeal のprovider版・実行予算・描画形式の拡充、
Seheweit の情報源別availability・収集予算・rollup・component別観測・HA/SNMP。
- 対象外:既存DBと本番データの変更、UIの改名、画像やロゴの利用、コンテナ分割、本番展開。
## 検証記録
2026-11-01、合成データと一時DBで以下を確認した。本番データへの操作は行っていない。
- `go test ./...` 成功。保存層・サーバー・CLI・設計書exportを含む。
- `go test -race ./internal/grammaratur -count=1` 成功。
- `go vet ./internal/grammaratur ./internal/compiler ./internal/render` 成功。
- `PAGESWIKI_BROWSER_TEST=1` の `TestEditorResilienceChromium` と
`TestHTMLProjectionChromium` 成功。編集・保存・競合・言語分岐・HTML保全と、
9つの表示/編集経路の安全性を確認。
- `git diff --check` 成功。
同日、Dregarnuhr の初期分離後にも以下を確認した。
- `go test ./...` 成功。store・serverを含め全Goパッケージの回帰テストを実行。
- `go test -race ./internal/dregarnuhr -count=1` 成功。
- store/serverの `TestDregarnuhr*`、`TestClaimDueEvent*` とコアの境界・実行制御試験を
race detector付きで実行し成功。外部カレンダーは実行せず、登録の確認だけを行った。
- `go vet ./internal/dregarnuhr ./internal/store ./internal/server` 成功。
- `git diff --check` 成功。今回ブラウザ試験の再実行はしていない。
同日、Geduldh の初期分離後にも以下を確認した。
- `go test ./...` 成功。保存・サーバー・CLI・DR・設計書exportを含む。
- `go test -race ./internal/geduldh ./internal/documentstore -count=5` 成功。
新旧入口の型・エラー・保存キー互換、並行保存、一時コピーの共有と回収を確認。
- store/server/DRの文書保存、バックフィル、Range配信、認可付き不変オブジェクト配信、
ZIPの部分取得、Materialize、snapshot/restore試験をrace detector付きで実行し成功。
- 保存失敗時のRevision非確定、DB競合時のpayload保全、Geduldhから保存したバイト列のDR復元を確認。
- `go vet ./internal/geduldh ./internal/documentstore ./internal/store ./internal/dr` 成功。
- `git diff --check` 成功。今回ブラウザ試験は再実行していない。
同日、Mestionora の初期分離後にも以下を確認した。
- `go test ./...` 成功。既存DBを読む任意診断は無効にし、一時DB・合成データのみで実行。
- Mestionoraの境界・認可・FTS実行計画をrace detector付きで3回反復し成功。
- store/serverを含む検索、City、型・エラー互換、Domain/alias分離のテストを
race detector付きで実行し成功。
- `go vet ./internal/mestionora ./internal/store ./internal/server` 成功。
- `TestSearchResultsChromium` 成功。1440pxと390pxでCity先頭表示、3表示モード、
フィルター、リンク、危険なHTMLの文字列表示と横方向のはみ出し防止を検証。画像も目視確認。
- 索引初期化・更新SQLはpackage/receiver/DBフィールドの移動以外が同一であることを確認。
- `git diff --check` 成功。ポリシーの遅延DB参照に伴う接続制約は後続TODOとして記録。
同日、Ordoschnellic の初期分離後にも以下を確認した。
- `go test ./...` 成功。既存DBを読む任意診断は無効にし、一時DB・合成データのみで実行。
- `go test -race ./internal/ordoschnellic -count=5` 成功。
バッチ上限、キャンセル後の終了保存、暗号化payload、HTTP分類、未設定clientでの送信禁止、依存境界を確認。
- store/serverの通知・Activity Subscription・Task Activity・失効済みfocus通知と新規配送試験を
race detector付きで3回反復し成功。並行claim、lease境界、旧attempt完了の拒否、
認証/Domain/受取人の不一致、focused延期、backoff、Inbox保全、checkpoint継続を確認。
- 追加した有界清掃・read-only拒否試験もrace detector付きで3回反復し成功。
- `go vet ./internal/ordoschnellic ./internal/store ./internal/server` と `git diff --check` 成功。
- 外部通知サービスへの送信・実端末Push受信・ブラウザ試験は今回実施していない。
UIとService Workerは変更せず、配送の障害競合は後続TODOとして記録。
同日、Schutzaria の初期分離後にも以下を確認した。
- `go test ./...` 成功。本番DBを読む任意診断を無効化し、一時DB・合成データで実行。
- `go test -race ./internal/schutzaria -count=5` 成功。親子制限の交差、肯定grantの範囲、
snapshotのコピー・並行参照、グループプロファイル、公開上限、予約Path、ユーザー領域、承認状態を検証。
- store/serverのPath・Locality・匿名公開・公開ナビゲーション失効・グループ継承失効・
governance・承認・endpoint判定をrace detector付きで2回反復し成功。
- 新規のstore型/JSON/エラー互換、4,096件上限、DB失敗時の不完全policy拒否試験を
race detector付きで3回反復し成功。
- `TestCityGovernanceChromium` 成功。隔離fixtureで所有者委譲・公開上限・アクセス設定を操作し、保存結果を確認。
- 抽出対象8ファイルのSQLリテラル(スキーマ・triggerを含む)が変更前と同一であることを確認。
- `go vet ./internal/schutzaria ./internal/store ./internal/server` と `git diff --check` 成功。
同日、Kunstzeal の初期分離後にも以下を確認した。
- `go test ./...` 成功。実Krokiではなくlocalhostの偽provider、一時DB・合成ソースを使用。
- `go test -race ./internal/kunstzeal -count=5` 成功。表示順・catalogコピー・kind/hash互換、
入出力上限、取消、エラー非開示、cacheの並行読取と原子的置換を検証。
- serverのKunstzeal・既存diagram認可分離・表示形式・hosted adapter設定・HTML projection等を
race detector付きで3回反復し成功。301/302/307/308の転送拒否、cache保存失敗時の表示継続も確認。
- 追加の由来情報なし/期限切れのディスクcache拒否試験もrace detector付きで3回反復し成功。
- `TestHTMLProjectionChromium` 成功。既存の9表示/編集経路で正本と表示の信頼境界を確認。
- registry定義は型名の公開化以外が同一であることを確認。nwdiagは実装済みcatalogに存在しないため、設計書の状態を訂正。
- `go vet ./internal/kunstzeal ./internal/compiler ./internal/server` と `git diff --check` 成功。
- 実Kroki・本番ネットワーク・取り込み済み外部カレンダーへのアクセスは行っていない。
同日、Seheweit の初期分離後にも以下を確認した。
- `go test ./...` 成功。本番DBの任意診断は無効化し、一時DB・合成データで実行。
- `go test -race ./internal/seheweit -count=5` 成功。JSON互換、情報源の失敗、proc読込上限、
容量のoverflow/underflow防止、I/Oの取得可否とprocess identity、並行収集、履歴windowを検証。
- store/serverのSeheweit・既存リソース監視・履歴・実行状態API試験をrace detector付きで3回反復し成功。
同一jobの重複防止、保持境界、bucket代表の互換、取消、read-only保存拒否、清掃失敗時rollback、
APIの期間fallbackと空配列、GETが履歴保存しないこと、認可・設定保持も確認。
- `TestExecutionMonitorChromium` 成功。隔離fixtureで実行状態・リソース画面と設定ダイアログを操作し、
監視間隔120秒の保存まで確認。2画面のスクリーンショットも確認。
- `go vet ./internal/seheweit ./internal/store ./internal/server` と `git diff --check` 成功。
- 本番DB・本番ネットワーク・取り込み済み外部カレンダーへのアクセスは行っていない。
8部品の初期分離はソース変更と検証まで完了。commit・push・本番展開は本作業に含めていない。
その後の明示的なリリース依頼により、同日 `v0.2.0` としてcommit・push・CI・本番反映を完了した。
[配布digest・移行・復旧点・開始ログ競合の継続課題](../../operations/deployments/2026-11-01-v0.2.0.md)
は初期分離の検証記録と分けて管理する。