Refactor architecture into eight components and consolidate reliability work
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s

Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts.

Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation.

Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
This commit is contained in:
Anya Tokugawa committed 2026-11-01 15:23:31 +09:00
1 parent 9dd425f765
commit d5d21b7841
302 files changed
+20037 -3492

No files matched your search

+397
View File
@@ -0,0 +1,397 @@
# DR詳細設計:通信・同期・主導権移譲契約
設計版:DR-D1、2026-09-27。**すべて次段階の設計。新endpoint・設定・永続化は未実装。**
責務と用語は [管理主系・データ主系](dr-authority-and-rejoin.md)、実装の順序は
[実施計画](dr-delivery-plan.md) を正とする。DB変更は本作業に含めない。
## 1. 構成と永続化の契約
### 1.1 Authority Service
manual providerは単一のoperator管理agentと専用のdurable操作台帳を使用する。
台帳は業務DB/snapshot外のローカル保護領域に置き、プロセス排他、revision比較、
operationの追記・fsync後の応答を必須にする。grant発行・holder変更にはoperator承認が必要。
同じ許可の短期renewは自動でもよいが、別boot/holderへの変更にはならない。
台帳破損/消失/別agent起動で自動再初期化せずblockedにする。manual provider自体のHAは
提供せず、復旧時は旧agentと全writerを隔離してtrust再承認する。これは独自分散合意ではない。
この運用台帳をアプリmetadataや管理manifest受理checkpointの代わりには使わない。
独立した運用サービスとしてgroup membership、grant、operation、fence証跡の参照を扱う。
coordinated providerはetcd v3の線形化readと比較更新transaction。業務nodeにはetcdの
任意Put権を与えず、認証されたAuthority Serviceの限定操作を通す。APIプロセスは複数起動できるが、
決定の正本は一つのetcd keyspaceであり、プロセスのメモリや通常event queueではない。
論理keyは `groups/{kind}/{uuid}/membership`、`.../active`、`resources/{uuid}/active`、
`operations/{operation_uuid}`、`trust/generation`。これはetcdの論理配置案で、アプリDBのDDLではない。
group/resource activeとoperation phaseの変更は同じCAS transactionで確定する。
共有bundleは関連全group/resourceを同じtransactionに含める。provider上限を超えるbundleは
登録時に拒否し、一部だけ切替えない。初期上限は1 bundleあたりgroup+resource合計32。
`active` は `{membership_revision, trust_generation, epoch, holder_node_id, holder_boot_id,
state, operation_id, resource_epochs, checkpoint_id, revision}` を持つ。
`state` は ACTIVE / REVOKING / FENCED / PREPARED / NONE。epochは10進文字列uint64、
上限でエラー。membership revisionとprovider revisionもJSON数値精度に依存しない文字列にする。
epochと操作intentはleaseに付けず保存し続ける。短期permitだけが期限付き。
### 1.2 契約インターフェース
| 契約 | 入力→結果 | 必須の性質 |
| --- | --- | --- |
| `ObserveAuthority` | group/bundle→membership、active、revision | 線形化read。watch/probeのcacheで代替不可 |
| `PlanTransition` | expected revision、target、reason→immutable plan/hash | 不足能力・影響・損失・必要承認を全列挙。副作用なし |
| `BeginTransition` | plan hash、承認、idempotency key→operation | CASで一つだけ開始、競合は409 |
| `RecordFence` | operation、provider evidence→FENCED | exact node/boot/resource/operationへの新鮮な証跡を検証 |
| `CommitGrant` | 検証ACK、fence、expected各revision→PREPARED | group/resourceを原子的に新holderへ。旧grantは復活不可 |
| `RenewPermit` | active grant、boot、nonce→短期permit | ACTIVE holder、またはPREPARED holderの限定初期化scopeだけ。期限更新は権限移譲ではない |
| `CompleteActivation` | writer gate/root検証ACK→ACTIVE | checkpoint/root、schema、grantの一致。未完なら配信不可 |
| `DescribeResources` | role→resource集合・能力 | aliasを含む共通正本を検出。未申告は独立と見なさない |
| `FreezeWriters` | bundle、operation、deadline→cut候補 | 新規受付停止、実行中writerをdrain。未知writerがいれば失敗 |
| `CaptureCheckpoint` | freeze token→checkpoint、pins | metadata/可変正本の同一cut、checksum、復旧に必要な参照集合 |
| `Stage/VerifyGeneration` | checkpoint、payload→verified ACK | 非稼働rootのみ。権限/互換性も検証し、writerを開かない |
| `ActivateGeneration` | verified ACK、grant→root ACK | root pointerをdurableに切替。曖昧な状態はrecovering |
| `ApplyControlManifest` | envelope、expected受理checkpoint→ACK | 内容・受理checkpointを同じ永続化境界でcommit |
PREPAREDではmigration/正本修復に必要な限定writerを新holderだけに許可できる。
通常リクエストとworkerはACTIVEになるまで閉じる。移行が長引けばpermitを更新する必要がある。
初段は同じschema/imageで復元し、DR切替にschema migrationを混ぜない。
`FreezeWriters` の成立はアプリDBの外から書くCLI等も止められる場合に限る。
未知writerが存在する保存profileは、サーバ/CLI全停止と外部保守lockによるoffline modeだけを許可する。
保存層で実現できない契約を、別ファイルへの二重書きで「同じtransaction」と称しない。
## 2. 信頼・ネットワーク
接続はHTTPS、TLS 1.2以上、mTLSによる専用node identityとgroup許可を必須にする。
検証無効化、HTTPフォールバック、通常Campus参加tokenの転用はしない。
既存の開発用 `--add-external-campus-http` はこのprotocolを許可しない。
初回信頼はoperatorがCA/鍵fingerprintとnode UUIDを別経路で承認する。probeによるTOFUはしない。
TLS終端proxyを用いる場合、外部からのidentity headerを除去し、信頼済みproxy接続だけで
検証済みidentityを伝える。加えて下記のnode署名で要求を束縛する。任意の
`X-Client-Cert` やFQDNだけで認証しない。FQDNの再利用・鍵変更はWARNING+quarantine。
peer endpointはoperatorが登録したHTTPS originと固定prefixのみ。ユーザーのURL入力や
probe応答の未知URLへ自動接続しない。redirectは禁止。私設networkの許可はgroupごとの
allowlistで定義し、DNS解決後の宛先IPも検証する。TLSのserver nameと登録originは維持する。
### 署名envelope
共通JSON envelopeは `protocol_version="dr/1"`, `key_id`, `payload_b64`, `payload_sha256`,
`signature_b64`。payloadはUTF-8 JSONの**送信した正確なbyte列**を署名し、再serializeしない。
署名対象は用途別固定prefix(例 `pageswiki.dr.probe.request.v1\n`)+payload bytes。
Ed25519を用い、種類の異なるenvelope間で署名を使い回さない。JSON重複key、未知version、
不正UTF-8、深さ過大、型違い、未知の必須capabilityを拒否する。canonical JSONの独自実装は不要。
通信payloadは `request_id`, `sender_node_id`, `sender_boot_id`, `group_id`, `group_kind`,
`membership_revision`, `trust_generation`, `nonce`, `issued_at`, `expires_at` を共通に持つ。
nonceは32 random bytesのbase64url、request_idはUUID。応答は要求ID/nonce/宛先node/bootと
要求payload hashをechoし、観測したauthority revisionを含める。nonce未要求・別boot・期限切れ
応答は状態遷移に使わない。UTC時刻の許容ずれは5秒、response有効時間は10秒以内を初期値とする。
時刻だけに依存せず、boot/nonce/authority revisionも検証する。
node用秘密鍵はnode-local。Campus manifest署名鍵とは別。信頼世代・鍵ローテーションは
旧新keyの承認期間と撤回revisionを記録し、同一nodeを二つのbootが同時に有効化しない。
要求payloadには `http_method`, `request_target`, `audience_id` も含め、実際のmethod/管理URI/
受信nodeまたはserviceに一致させる。署名検証前に別URIへrewriteしない。未知query、dot-segment、
encoded slashなどの曖昧なpathを拒否する。path groupとpayload groupの不一致も拒否する。
管理manifestの署名鍵をbackupから持ち出せても、Authority Serviceが確定したpublication receipt
なしに新manifestを受理させない。署名鍵を保持することと、現在の発行権限を持つことを分離する。
POSTの通信envelopeはJSON body、GETは8KiB以内の `PagesWiki-DR-Request` headerへ格納し、
GET bodyを要求しない。Range要求はその値も署名payloadへ含める。通常JSONの復号payload上限は
256KiB/深さ16、manifest pageだけは1MiBまで。binary転送の応答検証は署名済みmanifestの
chunk/全体hashで行い、全ファイルをbase64 JSONに包まない。
保管するcheckpoint/manifest署名は通信envelopeと用途prefixを分け、request nonceや10秒の
応答期限を付けない。不変artifactの由来/完全性検証と、今このnodeがアクセス・書込みできるかの
短期許可検証を分離する。古いartifact署名が有効でも現行のwrite grantにはならない。
## 3. probeと再参加
`POST /_/api/v1/instance/dr/probes` を認証済みgroup member/learnerだけに提供する。
無認証でpeer一覧、group一覧、snapshot一覧を返さない。
要求の追加項目:
```json
{
"group_kind": "data",
"group_id": "<group-uuid>",
"sender_node_id": "<node-uuid>",
"sender_boot_id": "<new-boot-uuid>",
"known_authority_revision": "123",
"known_epoch": "7",
"applied_checkpoint_id": "<checkpoint-uuid-or-null>",
"supported_protocols": ["dr/1"],
"capabilities": ["probe-v1", "offline-checkpoint-v1"],
"nonce": "<random-base64url>"
}
```
例は共通項目の一部を省略した型説明で、稼働設定として投入しない。
応答はprimary観測値、membership revision、state、checkpoint id/hash/親、
内容cut時刻、verified/applicableの区別、schema互換性、roleに応じたcontrol受理位置を返す。
資格情報・文書本文・ユーザー一覧・内部path・任意SQLは返さない。
probe結果は `observed`、AuthorityStore read結果は `authoritative` と区別する。
処理順:node identity→group所属→nonce等→protocol→authority照合→履歴照合→同期plan。
新しいepochを発見したら必ずauthorityへ再確認し、peerだけを根拠に旧許可を新primaryへ移さない。
矛盾の疑いがあれば自ノードのwriterは安全側へ閉じるが、他ノードの昇格は承認しない。
既知peerへ並列fan-outする。初期同時数4、groupごと最大32 endpoint、1応答256KiB、
要求/応答rateは1 nodeあたり10req/sまで。初回は即時、その後5秒±20%jitter。
失敗時は最大60秒までbackoff、安定した成功で戻す。タイマー終了はsuspect表示だけを変える。
membership変更はoperatorによるexpected revision付き操作。join要求はlearner候補に留め、
既存memberやauthority quorumを自動的に増減させない。
## 4. API境界とエラー
全URIは予定。通常ユーザーのPath/公開Domainからは独立した管理経路に置く。
| method / prefix以下のURI | 呼出主体 | 契約 |
| --- | --- | --- |
| `GET capabilities` | 登録node/operator | protocol、schema/profile能力。対応申告であり同期完了証明ではない |
| `POST probes` | group member/learner | 情報収集のみ。grantを発行しない |
| `GET groups/{kind}/{id}/status` | node/operator、範囲制限した管理者 | observed/authoritative/as_ofを明示 |
| `POST groups/{kind}/{id}/plans` | operator | rejoin / switchover / failover / reseedの副作用なしplan |
| `POST operations` | operator/認定済みpolicy executor | plan hashと承認を照合して開始 |
| `GET operations/{id}` | 許可された操作主体 | phase、未達条件、証跡、結果 |
| `POST operations/{id}/cancel` | operator | cancel可能点だけ。grant移譲後を勝手に巻き戻さない |
| `GET groups/{kind}/{id}/checkpoints/{id}` | 承認replica/operator | 署名metadata、transfer manifest参照 |
| `POST transfers` | 承認replica/operator | group/checkpoint/recipientを固定した転送session |
| `GET transfers/{id}/manifest` | session recipient | paged immutable manifest、snapshot ETag |
| `GET transfers/{id}/files/{file_id}` | session recipient | 許可されたopaque file IDのRange取得 |
| `POST transfers/{id}/acks` | session recipient | bytes受信/検証/適用ACKを別stageで記録 |
| `POST groups/{kind}/{id}/permits/renew` | active holderのみ | node/boot/epoch/resourceを束縛した期限更新 |
prefixは `/_/api/v1/instance/dr/`。node-local probe/transferはnode agentが処理し、
plans/operations/grantはAuthority Serviceが処理する。配置proxyは経路を区別し、
node agentがauthority不通時に代わりのgrantを作らない。
state変更要求は `Idempotency-Key: UUID` とplan/expected revision必須。同じkey・同じbodyは
同じoperationを返し、同じkeyで異bodyは409。応答喪失後は元operationをGETして照合する。
planの有効期間は60秒。membership、epoch、checkpoint、fence影響範囲が変われば期限内でも失効。
grant commit前にはもう一度最新条件を再検査する。
Web操作はoperator認可gatewayを介し、human actor・scope・承認内容・plan hashを短命の
delegationに束縛してAuthority Serviceへ渡す。nodeの秘密鍵やetcd資格情報をブラウザへ渡さない。
gatewayが認可しただけでimpact planの承認を省略しない。instance operatorの認可信頼源が
接続されるまではWeb applyを無効にし、ホスト運用者のCLIだけを提供する。
| HTTP | code例 | 呼出側の動作 |
| --- | --- | --- |
| 400 | INVALID_ENVELOPE / UNSUPPORTED_VERSION | 修正までretryしない |
| 401/403 | IDENTITY_REQUIRED / GROUP_FORBIDDEN | 権限修正。未知groupの内容は隠す |
| 404 | UNKNOWN_RESOURCE | 他groupの存在を推測できる詳細を返さない |
| 409 | STALE_EPOCH / OPERATION_CONFLICT / HISTORY_DIVERGED / WRITER_BOUNDARY_COUPLED | 再probeまたは新plan。自動上書きしない |
| 412 | MANIFEST_CHANGED / STALE_PLAN | 同一転送・旧planを継続しない |
| 413/429 | LIMIT_EXCEEDED / RATE_LIMITED | 上限内へ縮小、Retry-Afterを遵守 |
| 501 | CAPABILITY_UNAVAILABLE | offline/manualへ明示的に再計画。暗黙downgradeしない |
| 503 | AUTHORITY_UNAVAILABLE / NOT_READY / FENCE_UNCONFIRMED | 書き込みを閉じて待機 |
JSON errorは `code, message_key, request_id, retryable, operation_id`。本文・秘密・SQLは含めない。
管理レスポンスはno-store。状態取得はETag可、ただしcached statusを昇格承認には使わない。
### 配信とreadiness
管理listenerは一般DomainのHost選択/ログインsessionから独立して認証し、learning中もprobeを
受けられるようにする。復旧した業務DBの認証設定だけに、再参加の身元検証を依存させない。
通常routeはHost→Domain→DG→resource/grantの順に解決し、各要求で対象groupを判定する。
コントローラ用routeはCampus→CGを判定する。HTTP methodだけでどちらのprimaryか決めない。
node全体の `/health` は生存確認。複数groupで混在する場合、従来の `/health/write` は
対象listenerの全write groupがreadyなときだけ200とする保守的な集約値で、個別routingには使わない。
認証済みgroup statusの `read_ready`, `write_ready`, `state`, `reason`, `as_of` を
routing adapterへ渡し、切替時はfresh authorityと実際のgate状態も照合する。
PREPARED/ACTIVATINGは通常write readyにしない。既存接続も切替後の各要求で再検査し、
古い接続が旧primaryへの書込権を保持することはない。URIやHostをDRノードFQDNへ書き換えない。
## 5. Checkpointとバックアップ契約
### 5.1 内容
checkpoint v2(初版snapshot v1とは別format)は次を持つ。
- format/protocol version、group kind/id、dataset ID、checkpoint UUID、親checkpoint hash。
- source node/boot、trust generation、control/data/resource epoch、membership revision。
- snapshot cut ID、cut時刻、capture完了時刻、内容集合digest。
- app SemVer、image digest、保存profile、schema component/version/checksumの集合。
- DB snapshot descriptor、可変正本manifest一覧、CAS参照集合、総byte数、file数。
- 管理manifest受理位置、ACL/session失効watermark、outbox/job再送判定位置。
- 暗号化方式・key参照・別保全のsecret一覧。secret値は一覧に含めない。
- 操作状態 `capturing/sealed/transferring/verified/activated`。sealed前はservableにしない。
「送信完了」「受信した」「hash検証済み」「配信可能」「昇格可能」は別。
checkpoint sequenceはその系列の順序であり、clientへ成功応答した全変更の境界とは限らない。
初段のsnapshot同期は物理snapshot+CAS不足分転送。SQL差分適用やWALファイルの独自転送はしない。
オンラインのtransaction log方式は保存層が将来別profileとして保証するまで使わない。
### 5.2 一貫したcapture
1. capture対象のbundle/resourceを確定し、schema変更と同時に走らないことを確認する。
2. 新規writer受付を閉じ、DB・可変正本の処理中更新をdrainする。GCも対象世代を消せない状態にする。
3. 保存層に同一cutのDB snapshotと可変正本manifestを固定させ、参照集合を確定する。
4. 参照CAS/月別世代へのdurable pinを確立する。pinの永続化とcut固定を確認する。
5. sealedしたDB像・metadataから後続コピーできることを確認してbarrierを解除する。
6. 大きな不変payloadのhash確認/転送はforegroundより低優先度で継続する。
SQLite Backup APIはDB単位の整合コピーであり、別ファイルの同一cutまで自動保証しない。
DB像の固定にコピー完了まで必要なprofileでは、その間barrierを維持する。
「短時間online」と無条件に表明せず、barrier予算超過ならpublish前にcaptureを中止し、
primaryを再検査して通常処理へ戻す。最初はoffline profileだけでもよい。
[SQLite Backup API](https://www.sqlite.org/backup.html)
pinの保持はtransferの期限と独立。transfer sessionが切れても、保全世代/進行中operationから
参照されるblobを消さない。完了/中止後もretentionに従って解放する。ノード再起動でpinが
失われるprofileはオンラインcapture不可。保持台帳の実装は保存担当の契約に従う。
### 5.3 受信・再開・切替
受信は非稼働generationに対して行う。file IDはmanifest内でscope付きに割り当て、
任意pathや他groupのhashを直接読めるAPIにしない。manifestは1page最大1,000件/1MiB、
sealed manifestのroot digestとpage hashで全体を検証する。各payloadは全体hash/sizeと
16MiB単位のchunk hashを持ち、Range再開時にもchunkと全体の両方を検証する。
転送sessionはrecipient node/boot、group、checkpoint、期限に結び付く。初期期限15分、
再認証後に同じsealed checkpointへ再開可能。期限はreaderの権限であり正本の寿命ではない。
宛先の空き容量は必要byte+20%と運用予約分を確認し、既存稼働世代を自動削除して空きを作らない。
受信後:全payload→DB/正本参照整合→schema互換→失効/鍵の可用性→内容digestの順に検証する。
DB inspectionはread-onlyで行い、初期化/migrationによって検証対象を変化させない。
検証ACKを受けても一般routingは開かず、standbyのread条件または新grantを別途確認する。
root切替は新generationをfsyncした後、atomic pointer更新で行う。旧世代を保持し、
再起動時にpointerとoperation recordが食い違えばrecoveringで照合する。
転送負荷の初期値:nodeごとpayload stream最大2、合計10MiB/s、hash worker 1、
foreground高負荷時は新chunk受付を停止。制御用probe/permitは別connection・別予算。
リソース監視値が取れない場合は固定上限を維持し、無制限へ拡張しない。
pause/backoff/cancelの最大応答遅延は1 chunkのI/O期限内。候補値30秒、実測して認定する。
通常event schedulerにはcapture/verify/転送等を表示するが、grant更新は専用loopとする。
### 5.4 保全・秘密・分岐
複製は保全世代の代替ではない。retention初期案は直近3+日次7+週次4、導入時に容量確認する。
世代依存とpinsを検査してから削除し、root trust/復号鍵の保全はsnapshotとは別の障害領域に置く。
業務復旧に必要な暗号化鍵は許可済みgroup nodeへ保護して配布するが、物理nodeの専用秘密鍵は
他ノードへ配布しない。初版が保全するlegacy instance keyとは移行時に区別する。
復帰ノードに現primaryの系列にない変更があれば、旧DB/正本を隔離したgenerationとして保全する。
件数・由来・時点を示し、手動export/importや内容比較へ渡す。データの新旧をmtimeだけで比較せず、
自動マージ、自動削除、旧DBの現primaryへの逆コピーを禁止する。
## 6. 管理manifestの世代設計
既存schema_version 1/2、署名と受理checkpointを維持し、新契約は **schema_version 3案** とする。
未対応受信先が一つでも対象に含まれる間はv3配信/CG自動移譲を有効化しない。
capability応答だけでなく、移行済み受理状態のACKを必要とする。
v3 payloadは既存管理情報に `control_group_id`, `trust_generation`, `control_epoch`,
`manifest_sequence`, `configuration_checkpoint_id`, `previous_manifest_hash`, `payload_hash`,
`authority_commit_receipt` を追加する。署名は確定した管理内容を一度だけserializeしたbyte列に行う。
発行手順:同じ管理snapshotから内容を取得→候補payloadを永続化→有効control grant下で
authorityへ `expected previous hash/sequence` によるpublication commitを要求→返却receiptと
署名を保存→配信。応答喪失なら同じpayload hashでcommit結果を照合する。新規内容に同じsequenceを
割り当てない。receiptのない「大きなepochのmanifest」は配信・受理しない。
snapshot内容の取得とcheckpoint固定は保存担当の契約が必要で、既存の連番SQLだけで代替しない。
受信手順:
1. Campus/CG/署名鍵/trust世代/対象Domain ownershipを検証する。
2. authority receiptと、現在許可されたcontrol epochを確認する。epoch切替時はfresh authority確認必須。
3. 同epochの小さいsequence、同sequenceで異hash、親hash不一致は拒否する。
4. 同epoch・同sequence・同hashは冪等ACKとする。
5. 新epochは署名済み移譲recordとbase管理checkpointを検証する。単なる数値の大小では許可しない。
6. 管理内容と受理位置を一つのtransaction境界で保存し、そのcommit後に適用ACKを返す。
管理ノードprobeから回収した最大受理位置は「これより前へ戻してはいけない」下限の証拠。
完全な管理正本の代わりではない。checkpointが不足すればCGはblockedとし、新epochを使って
古い権限を再発行しない。復旧snapshotがauthorityの最後のpublicationより古い場合は、
正しい履歴の取得または運用者による明示的な再構成・失効再適用を要求する。
v1/v2からの移行は最後のrevision/hashをmigration anchorとして固定し、最初のv3がそれを参照する。
trust pinを削除してやり直す方法は採らない。v3受理後のv1/v2自動fallbackも拒否する。
この永続化の追加は将来のDB担当との合意対象であり、本設計作業では実装しない。
## 7. 計画切替とpreempt
preemptはpreferred nodeへ向けたswitchover operationをpolicy executorが作るだけであり、
特別な高速昇格経路を持たない。offなら現primaryを維持、manualなら提案のみ通知する。
automaticでも安定時間/時間帯/cooldown/能力/影響範囲を満たさない限りplanをapplyしない。
| operation phase | 確定させること | crash/timeout時 |
| --- | --- | --- |
| PLANNED | target、expected構成、影響、必要能力、見込時間 | 期限切れで再plan。副作用なし |
| VALIDATING | authority最新値、target同期/鍵/schema/ACL、fence能力 | 旧primaryの権利は変更せず停止 |
| DRAINING | 旧primaryの新規write/job停止、実行中処理の結果 | 旧grantがまだ有効とauthorityで確認できる場合だけdrain解除可能 |
| SEALED | final cutと内容集合、targetの最終検証ACK | 不足があれば旧権利の扱いを照合。勝手に切替えない |
| REVOKING | 旧permit再発行禁止を永続化 | ここから旧epochの自動復活は禁止 |
| FENCING | 旧writerへの外部隔離と、その確認証跡 | 不明ならblocked。新grantなし |
| GRANTED | 新epochのgroup/resource許可をPREPAREDで確定 | holderをGETで照合し再開。別targetへretryしない |
| ACTIVATING | target root/gate/schema/readinessを検証 | targetを隔離、次のoperationを計画。旧系に単純rollback不可 |
| ROUTING | TLS/Host/接続先を更新しread/write確認 | 新primaryは一つのままrouting修復 |
| COMPLETED | sourceの降格、監査、Inbox、保持世代を記録 | 重複完了は冪等 |
planned switchoverの損失許容は常に0。最終cutのDBだけでなくCAS・可変正本・失効・outboxも
targetに適用済みでなければSEALEDを超えない。「遅延がほぼ0」「同期率100%表示」だけでは不可。
grantを移す瞬間はwriterが一時的に0になってよいが、2になってはいけない。
fence証拠はkind、provider、対象node/boot、対象resource、操作ID、確認時刻、結果、
再起動/再接続を阻止する方法を含める。接続不能やSIGTERM送信済みだけではconfirmedにならない。
初段の自動認定は全旧writerを確実に隔離できる外部providerだけ。保存側fencing契約が後で
認定されれば、影響範囲を小さくするprofileとして追加できる。
**fenceで認定する範囲:** HTTP/LB経路を閉じただけではローカルjob/CLIの書込を止められない。
プロセス停止なら全writerと再起動経路、電源断なら同居group、保存資格情報の失効なら対象となる
すべての正本backendを対象にする。remote backendへ既に送った可変正本更新が遅れて完了する
可能性も評価する。認定された保存側世代拒否、drain確認、または明確な処理終了証明がなく、
旧更新が後から確定し得るprofileでは新grantを出さない。単にtimeoutを待ったことは終了証明ではない。
メール等の既送信副作用はfenceで取り消せないため、outboxの曖昧結果は別途照合・承認対象にする。
## 8. 障害時昇格と許可喪失
障害時はprobe失敗でsuspect表示→authority照合→fence確認→最後の検証済み世代と損失評価→
新grant、という順。旧primaryと最終cutを交渉できないため、計画切替と同じ0損失を仮定しない。
RPO内というだけでは、成功応答済みの更新が失われない証拠にならない。
DR-D1の既定は未知損失/未複製変更があればoperator承認必須。自動failoverは保存profileが
`acknowledged_writes_durable_on_replica` を提供し、authorityがその確定境界を照合できる場合に限る。
現在の非同期snapshot profileはこの能力を持たないので、自動preemptは将来可能でも、
無人・無損失failoverまで実装済みとはしない。許容損失による自動昇格profileは本版では提供しない。
短期permitの初期候補はTTL30秒、更新5秒、local safety margin10秒、更新RPC期限2秒。
有効期限を受信時刻だけから延長せず、要求開始のmonotonic時刻と署名された有効期間から
保守的なlocal deadlineを計算する。遅れた応答、clock異常、別boot、別epochは破棄する。
許可喪失でwriter gateを閉じるが、プロセス停止/遅延commitの安全性はそれだけに依存せず、
次holderにgrantする前の外部fenceで保証する。TTLが経過しただけの自動grantは禁止。
旧nodeが復帰しても、既存許可をdiskから復活させない。nonce付きprobeと新bootに束縛した
fresh permitが必要。authority自身が復元され旧recordしかない場合は全体をblockedにする。
## 9. cancellation、監査、rollback
operationは長時間処理なので202を返し、通常event/queue画面には参照を出す。
authorityのphase更新は通常キューの「再試行」ボタンで巻き戻さない。
同じ操作を複数executorが拾ってもCAS phase+idempotency key+fence providerの操作IDで重複を抑える。
外部副作用のexactly-onceを無条件に約束せず、曖昧な送信結果は照合またはoperator確認にする。
REVOKINGより前は、現grantが旧holderに有効と確認できる場合にだけcancelして復帰できる。
REVOKING以降の失敗は新しい復旧operationと新epochで処理する。以前の設定ファイルに戻すだけの
rollback、epoch減少、旧writerの再起動、受理checkpoint削除は禁止。
監査はactor、group/bundle、plan hash、old/new node/boot、各epoch、checkpoint、損失承認、
fence証跡参照、phase、結果、request IDを残す。書き換え可能な業務snapshot内だけを監査の
保全先にしない。probe全件は短期集約し、状態変化と操作の証跡は長期保存する。
## 10. 不変条件
- N1:同じwriter resourceに二つの有効holderを同時に作らない。
- N2:probe、priority、preempt設定、watch通知は単独でwriterを開けない。
- N3:新epochで古い管理内容/権限を無条件に正当化しない。
- N4:未検証・不完全なgenerationへactive pointerを向けない。
- N5:旧primaryの未同期変更を保全せずに削除・上書きしない。
- N6:通常DBのrestorationでnode trust/authorityの単調性を巻き戻さない。
- N7:すべてのwrite経路と背景処理がgate/隔離の範囲内にある。
- N8:control切替とdata切替を区別し、共有resourceの場合だけ明示的に連動する。
- N9:grant移譲後の失敗を旧epoch復活で回避しない。
- N10:不足能力・到達不能・曖昧な副作用はfail closedにし、成功と表示しない。