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

18 KiB

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 作者の説明。 名前の参照表は プロジェクト作者の Gist。 以下の英字表記は 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 を参照。
  3. Geduldh 初期分離:既存 documentstore.Store 契約をaliasで維持し、 ローカル保存と検証付き一時展開の実装を internal/geduldh に分離。 filesystem layout、hash、Range、streaming、移行・DR手順を変えない。 大きな store パッケージ全体の改名はしない。文書保存契約と残件 を参照。
  4. Mestionora 初期分離:SQLite検索・索引・City検索を分離し、 呼出し元の権限判定と既存の候補・抜粋予算を維持。検索と索引契約 を参照。
  5. Ordoschnellic 初期分離:Web Pushの有界配送・再試行・暗号化を抽出し、 Inboxの原子的登録と購読checkpointを維持。再送が起こり得る既存の保証範囲を変更しない。 通知配送契約と残件 を参照。
  6. Schutzaria 初期分離:DB非依存の読み取り・Locality・グループ・公開範囲・承認状態評価を分離。 認証・DB読込・公開確定transactionは既存側に残す。権限評価契約と残件 を参照。
  7. Kunstzeal 初期分離:ビルトイン表示方式の選択、Krokiの有界描画、図hash/cacheを分離。 認可・ソース由来・CSPを維持し、redirect拒否とcache原子的置換を追加。描画契約と残件 を参照。
  8. Seheweit 初期分離:リソース収集と履歴保持・bucket規則を分離。現在値APIと背景監視を接続し、 収集読込上限・容量計算・取消/read-only保存を補強。認可とSQLは既存側に残す。観測契約と残件 を参照。

この移行は配置変更、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・移行・復旧点・開始ログ競合の継続課題 は初期分離の検証記録と分けて管理する。