Articles on Rindrics Mumbles

データ登録処理に関する技術選定: Revision IDの生成アルゴリズム

Mon, 28 Sep 2026 00:00:00 +0900

data-registryによるRevision ID生成アルゴリズムにUUID v7を選択した。

背景

資源評価に利用するデータの永続化を担うdata-registryの開発をすすめている。

Tag "data-registry" | rindrics.com

https://rindrics.com/tags/data-registry/

前回の記事では、冪等性キー生成に用いるハッシュアルゴリズムを選んだ。本記事では、永続化処理が実行される際のRevision IDの生成方法について考える。

要件

現時点で、data-registryには下記のユースケースが見つかっている:

版の履歴閲覧: あるデータセットの変更履歴を時系列で表示したい
データ登録要求の並行受信: 複数人のユーザーが複数シナリオを並列計算し、それらのクライアントからの登録要求を受信した

上記から、Revision IDの生成は、以下の要件を満たす必要がある:

要件	説明	要件ID
一意性	各Revisionは一意のIDを持つ	SR001
不変性	一度生成されたら変更されない	SR002
時系列順序付け可能性	同じRevision chain内で自然にソート可能	SR019
分散生成可能性	Coordinatorなしで各プロセスから生成可能	SR020

ここで、不変性（SR002）については実装の責務として考慮外とし、残りの要件を満たすID生成アルゴリズムを選定する。アルゴリズムには複数の候補が考えうるが、詳細な検討の手間を軽減するには、まず時系列順序付け可能性を根拠に選択肢を刈り込むとよさそう。

候補アルゴリズム

ID群が時系列で順序付けされるためには、IDは時刻情報を含むtimestamp-basedな手法で生成される必要がある。

これに着目すると、例えばNanoidやUUID v3, v4, v5, v8は検討対象から除外でき、候補としては下記が残る:

なお、timestamp-basedな手法としてはUUID v1およびv6も含まれるが、これらと比較した場合にはv7が推奨されている（スーパー意訳）ため検討候補から除外した。

候補アルゴリズムの比較検討

連番（✘ 不採用）

その名の通り、連番の整数をIDに使う方法。

ID: 1, 2, 3, 4, ...

この手法の利点はストレージのオーバーヘッドが少ないことだろう。表現はシンプルだが、それを実現するアーキテクチャや実装は必ずしもシンプルとは限らない。 2種類の実現方法「データベースレベル」「アプリケーションレベル」それぞれについて、pros/consを整理してみる。

方法A: データベースレベル

PostgreSQL の SERIAL/BIGSERIAL（自動採番機能）を利用する方法。

pros:
- ✔ 採番の責務をデータベースに持たせられる
- ✔ ロック時間が短い
cons:
- ✘ 単一のprimary writerに依存
- ✘ スケーラビリティ: 並行タスクが全て同じDBに集約

方法B: アプリケーションレベル

採番の責務をアプリケーションで持つ構成。この方法をとるとデータベースについては水平スケールが自由になるが、結局ほアプリケーションレベルに移ってきた採番の責務がボトルネックになる。

つまり、連番形式は宿命的に「最後の値は何か」というグローバルな状態管理に依存する方法で、この状態は必ずどこかに集約されることになる。結果として、SR020（分散生成可能性）を満たさないため不採用とする。

Snowflake ID（✘ 不採用）

Twitterなどの大規模分散システムで運用実績のある手法。

ID: 175638572750991360
     ├─ timestamp(ms)
     ├─ machine id
     └─ sequence

pros:
- ✔ 大規模分散システムでの運用実績あり
- ✔ ストレージ効率がよい
cons:
- ✘ Machine IDの事前割り当てが必須（新規マシン追加時に管理が必要）
- ✘ 各machineが自身のsequenceを管理する必要がある

ストレージ効率の良さは魅力的だが、プラットフォームの潜在ユーザーの規模を考慮すると、machine IDの割り当てなどの運用オーバーヘッド増加がペイされるとは考えにくい。 data-registryにおける採用は見送ることにする。

UUID v7（✔ 採用）

UUIDの一つ。タイムスタンプベースのフィールドを備えつつ、同タイプの先行バージョン（v1およびv6）に比べてランダム特性が向上している。

ID: 0189a5c5-a92b-7b47-b5ad-e6c3cb6c41e9
   └─ from timestamp ─┘

pros:
- ✔ 決定的に生成できるため各ノードで独立生成可能
- ✔ 高いB-tree局所性による高速書き込み
- ✔ 標準性（cf: RFC 9562）
- ✔ エコシステム充実: Clojureでもライブラリを利用可能
cons:
- ✘ タイムスタンプ衝突にはランダム¹部分のみで対処する必要がある
  - TODO: ランダム部分のビット長が最悪ケースをカバーするか確認する

短所もあるものの、これらはdata-registryのユースケースにおいては問題にならないかもしれないので、実際に試算してみる。

同タイムスタンプ内における一意性違反リスク

UUID v7では、同じミリ秒内に複数のIDを生成する場合、一意性の保証はランダム部分（74ビット）で対処する必要がある。この問題をキューイングなどのアーキテクチャで解決しない場合において、UUID v7のエントロピー性能がdata-registryの最悪ケースをカバーできるかを見積もる。

この問題は誕生日問題と同じなので、並行プロセス数を$n$は、ランダム部分のビット長を$b$とすると、衝突確率は下式で表される:

$$ P(\text{1組以上が衝突}) = 1 - \frac{1}{e^{\frac{n (n - 1)}{2^{b+1}}}} $$

いま1,000,000の並行プロセス（1,000ユーザー × 1,000シミュレーション）が同ミリ秒内にIDを生成する場合、$n = 10^6$、$b = 74$なので、衝突確率は

$$ \begin{aligned} P(\text{1組以上が衝突}) &= 1 - \frac{1}{e^{\frac{10^6 (10^6 - 1)}{2^{75}}}} \\ &\approx 1 - \frac{1}{e^{\frac{10^{12}}{3.8 \times 10^{22}}}} \\ &\approx \frac{10^{12}}{3.8 \times 10^{22}} \\ &\approx2.63\times10^{-11} \\ &= 2.63\times10^{-9} \text{\%} \end{aligned} $$

となり、ピーク時リクエストに対してアーキテクチャによる緩衝を挟まない場合にも、UUID v7のエントロピー性能は充分な安全マージンを持つことがわかった。

以上から、data-registryにおけるRevision IDの生成したアルゴリズムにはUUID v7を採用する。

所感

本記事でも、前回の記事と同様に、最悪ケースに対するキャパシティ見積もりに基づいて技術選定した。実際には、最悪ケースに対してアーキテクチャ的な解決を挟まない場合にはID衝突以前に別の問題（スループットなど）が生じそうだが、ひとまずの物理的な猶予は把握できた。大規模アーキテクチャにおける成功例: Snowflake IDも一応は検討したが、個人開発における運用性を考えると選べなかった。

次回は、Revision IDと冪等性キーの永続化方法について考える予定。

疑似乱数であり、実際は決定的に生成する。 ↩︎

冪等性キー生成に関する技術選定: ハッシュアルゴリズム

Wed, 23 Sep 2026 00:00:00 +0900

冪等性キーの生成に利用するハッシュアルゴリズムとしてBLAKE3を選定した。

はじめに

資源評価に利用するデータの永続化を担うdata-registryの開発をすすめている。

Tag "data-registry" | rindrics.com

https://rindrics.com/tags/data-registry/

前回の記事では、冪等性キーをサーバー側で生成する意思決定をした。本記事では、その冪等性キー生成に用いるハッシュアルゴリズムを選ぶ。

背景

通常、ハッシュアルゴリズム選定における比較観点は下記の通りだ:

衝突耐性
計算コスト
標準性
相互運用性
出力サイズ

ただしこれらの観点の重みは均等ではなく、特にdata-registryの冪等性キー生成においては何よりも衝突確率の低さを重視する必要がある。

「衝突確率の低さ」とは

攻撃による衝突ではなく、単なる確率的な衝突が起こる程度を指している。理由としては、本ケースではセキュリティ目的で利用するわけではないので、「攻撃への耐性」という観点は必要ないため。

これは、冪等処理において、ハッシュ衝突が起きた場合に下記の流れでデータ喪失が生じるためだ:

先行リクエストA: hash(何らかのデータ) → hash=H
  → Revision "newRev" が作成される → 返却

後続リクエストB: hash(何らかの別のデータ) → hash=H (衝突)
  → ルックアップで "newRev" を発見 → 返却
  → クライアントは成功を受け取るが、登録依頼したデータは登録されていない（データ喪失）

このたび選定対象とした候補アルゴリズムは下記の三つ¹:

SHA-256
SHA-512
BLAKE3

上記のうち、まず衝突確率の低さが想定リクエスト数に照らして必要十分なものを選び、続いてその他の選定観点を比較して採用アルゴリズムを決める。

衝突確率に着目した一次選定

ということで、まずアルゴリズムの衝突確率がdata-registryの想定リクエスト数に照らして高すぎないかを調べてみる。 SHA-256とBLAKE3はともに出力長が256ビットで衝突確率は同じなので、まず出力長256ビットにおける衝突ペア数の期待値が想定リクエスト数のもとで1未満に収まるかを調べることで候補を絞る。 256ビットで足りなければSHA512の衝突確率の概算に進み、一方で256ビットで充分であればSHA256とBLAKE3の比較に進むということ。

衝突確率は要は誕生日問題として考えることができるので、$k$個のリクエストから得られるハッシュ値について、衝突するペア数の期待値$E[C]$は、ハッシュ出力を$b$ビットとすると次式で近似できる。

$$ E[C] \approx \frac{k^2}{2^{b+1}} $$

衝突が十分まれな範囲では、1組以上の衝突が発生する確率も次式で近似できる。

$$ P(\text{1組以上が衝突}) \approx \frac{k^2}{2^{b+1}} $$

したがって、いま考える256ビットのハッシュでは、

$$ E[C] \approx \frac{k^2}{2^{257}} $$

となる。

選定にあたっては、衝突するペア数の期待値が1となるリクエスト数を求め、それが想定リクエスト数に対して余裕があるかを確認する。

256ビットの場合、

$$ \frac{k^2}{2^{257}} = 1 $$

より、

$$ k \approx 2^{128.5} \approx 4.8 \times 10^{38} $$

となる。

利用程度に関するパラメータ

想定リクエスト数の算出に必要なパラメータを、オーダー規模で見積もる。見積もりは悲観値で出したいので、オーダー単位で切り上げた値を利用する。

ユーザー数

水産研究・教育機構の「水産資源に関する情報」ページを見ると、本記事の執筆時点（2026年9月）において 沿岸沖合資源（192魚種） という記述がある（こんな多かったっけ…？）。 192魚種それぞれの主担当者は、ほぼ確実に延べ人数つまり兼務があると見てよいと思うが、ここでは悲観見積もりとして一応192人の主担当者がいることにする。

また資源評価プラットフォームに機能を充実させた場合、評価案査読者や、認証済みの（物好きな）一般利用者からの利用も考えられる。合計ユーザー数をオーダー規模で見積もるにあたり、これらの利用者が808人を超えるようだと1000人のオーダーとなるが、まずそんなことはないだろう。

ということで、ユーザー数は多くても数百人のオーダーに収まると考えられ、見積もり用に切り上げオーダーとしては 1000人 を用いる。

運用期間

資源評価事業は将来的にも継続するだろう。 10年未満ということはないはず。しかし1000年はいくらなんでもやりすぎだろう。その頃にはもっと良い技術があるはず。

ということでオーダーとしては 100年。

ユーザーあたり並列計算数

資源評価プラットフォームがいい感じに構築できるとしたら、パラメータセットの組み合わせが異なる複数シナリオをバックグラウンドで並列計算できるようにしたい。並列計算機能が実現した場合、ユーザーごとに並列計算ジョブを持つことになる。各ジョブに書き込み系の処理をさせるかどうかは設計次第ではあるが、ここでは悲観見積もりということでユーザーあたりの並列計算数も考慮しておく。

実用的な視点に立つとは、並列計算の単位としては、名前をつけられるようなレベルの大きいシナリオだけでなく、パラメータの探索などでも利用する局面があるだろう。そう考えると、10のオーダーの並列計算はあまり嬉しくないだろうと思う。百数十とか、数百の並列計算ができると、探索的検討がスムーズにできるはず。

ということで、数百を切り上げるとオーダーとしては 1000。

バースト利用期間

悲観的に見積もるため、ここではバースト利用が資源評価の準備期間中にわたって続くと仮定する。

なお事業の性質上、資源評価プラットフォームは年間通して平均的に利用されることはない。 data-registryが冪等性キーを生成する想定リクエスト数に関しては、利用はほぼ評価期間に限られるだろう。このことから、定常利用はバーストに対して無視できる程度と思われる。

ということで、バースト利用が3ヶ月間続くとし、オーダー単位で切り上げて 100日。

リクエスト数の見積もり

上記から、data-registryの冪等性キー生成リクエスト数の悲観見積もりのパラメータは下記のようになった:

ユーザー数: 1000人
運用期間: 100年
ユーザーあたり並列計算数: 1000
バースト利用期間: 100日

このパラメータもとでは、衝突ペア数の期待値を1未満に保つうえで、1ユーザーが発行できる年間のリクエスト数は

$$ \frac{4.8 \times 10^{38}}{1000 \times 100 \times 1000 \times 100} = 4.8 \times 10^{28} $$

となる。

実際には、ユーザー数も運用期間もここまでにはならないと思われるので、並列計算数もまだ増やす余地がある。以上から、アルゴリズムのアウトプット長は256ビットで充分と思われたため、SHA512は選択肢から外す。

ということで、以下では、SHA256とBLAKE3を、残る3観点について比較する:

~~衝突耐性~~ 衝突確率の低さ
計算コスト
標準性
相互運用性
~~出力サイズ~~
- ともに256ビットのためスキップ

その他の観点での比較

SHA256

計算コスト: こちらのベンチマーク結果によると、5 MBの写真ファイルのハッシュ化の所要時間が139.10 msということで、処理速度は35.9 MB/sとする
標準性: 米国国立標準技術研究所（NIST）により仕様化されており充分
相互運用性: 実質上の業界標準なので充分

BLAKE3

計算コスト: こちらのベンチマーク結果によると、5 MBの写真ファイルのハッシュ化の所要時間が38.00 msということで、処理速度は131.6 MB/sとする
標準性: RFC準拠の仕様が公開されており充分
相互運用性: 主要言語に対応しており、ClojureでもJavaライブラリをJava interop経由で利用可能なので充分

比較観点をまとめると下記のようになる:

Algorithm	処理速度	標準性	相互運用性
SHA-256	35.9 MB/s	✔	✔
🥇 BLAKE3	131.6 MB/s	✔	✔

その他、CPU負荷やメモリ効率についてもBLAKE3の優位性が報告されていた（ref）。

以上から、標準性・相互運用性は両アルゴリズムともに良好なため、計算コストの低さを重視してBLAKE3を採用する。

所感

今回のケースでは、採用技術のスペックが非機能要件を大幅に上回っていたために、些細なことを大げさにやった感があるかもしれない。しかしこれをやらないと、「キャパ的に3日と保たないシステムを作ってました」みたいな事態にもなりかねない。仰々しくはあるが、やはり必要なのだ。

次の記事では、Revision IDの生成方法について考える予定。

2026-09-26追記

もともとは冪等性キーの生成を安定化するためのJSONのcanonicalizationについて考えようとしていたがやめた。理由としては、フィールド順の違う同等のデータなどのように、表現に揺れがあるものが冪等処理されなかったとしても、ストレージが多少浪費されるだけで深刻な問題とはならないと判断したため。なにか問題が起きたらそれから考える。

セキュリティ目的での利用ではないが、MD5とSHA-1については候補から除外した。理由としては、両者の衝突耐性が破られているため採用が減り、コミュニティ内でライブラリや情報の更新が途絶える懸念を回避するため ↩︎

冪等性の設計〜等値性の判定場所をユースケース駆動で決める

Mon, 14 Sep 2026 00:00:00 +0900

data-rigistry開発の前回記事からだいぶ間が空いてしまったが、久しぶりに時間をとれたので冪等性について考えてみる。

はじめに

資源計算に利用するデータを登録するためのサービスdata-registryを作っている。

下記は前回の記事。

イミュータブルなデータレジストリの設計とAlloyによる形式検証 | rindrics.com

https://rindrics.com/articles/immutable-data-registry-alloy-design/

上の記事では初期設計をやってみたのだが、反省点がいくつかあった:

要件定義が雑だった
スコープを決めていなかった
進め方の戦略がなかった

そこで本記事では、前回の反省を活かし、「取り組むスコープを決めた上で」「ユースケース駆動で要件・仕様を吟味」する「という方法で進める」ことにする。

本記事で扱う問題のスコープは下記の通り:

等値性の定義
ユースケースの整理
冪等性キーの生成場所と等値性の判定場所の決定

冪等性が必要な理由

冪等性が必要な本質的な理由は2つ：

クライアント実装の簡潔性
- 再試行時に「同じリクエストを送ってもいい」という保証があれば、クライアント側で「送信完了か確認不可か」を区別する必要がない
- 再試行戦略が単純になる
並行処理時の安全性
- 複数プロセスが同じデータを登録する場合、競合を避けて結果の予測可能性を確保
- 「どのRevisionが実際に採用されるのか」が明確になる

特に、意図的な再試行ではなく、並行リクエストやネットワークエラーによる自動再試行への対策のために導入する。

等値性の定義

サービスの冪等なふるまいを設計していくにあたり、まずはどんなときに冪等性が保証されるべきか: つまりdata-registryが扱うペイロードの等値性について考えてみる。

このサービスの性質を考えれば、登録対象のデータそのものの等値性が考慮される必要があることは自明。また、等値性を考えるうえでのヒントとして、既存のシステム要件 SR004 を考慮するとよい:

SR004 新しい版は、既存の版を0個または1個参照しなければならない

データ登録要求の仕様は決まっていないものの、新しい版を紐づける先の parentRevision の値については、少なくとも等値性に関わる情報と考えてよさそう。

上記から、data-registryにおける等値性の定義は下記の通りとする:

等値とみなすリクエスト = hash(parentRevisionId, hash(data))が同じリクエスト

ユースケースの明確化

ペイロードの等値性をひとまず定義できたところで、続いて冪等性に関するユースケースをまとめていく。

リクエスト処理時のユースケース

まず、data-registryのクライアント側で発生する機能的なユースケースを考えてみる。

並行リクエストを冪等に処理する

概要: 複数のプロセスから並行で同一の内容のリクエストが届いた場合に呼び出される
期待: リクエストが一つだけ届いた場合と同様の状態になる
アクター: プロセスA、プロセスB
メインフロー:
- 1: プロセスAが、システムにデータの登録を要求する
- 2: プロセスBが、システムにデータの登録を要求する
- 3: システムは、プロセスAに要求されたデータを永続化する
- 4: システムは、永続化が成功した旨のメッセージをプロセスAに返却する
- 5: システムは、プロセスBの要求がプロセスAと同一であることを検知する
- 6: システムは、永続化はせずに、プロセスBに対してプロセスAと同一の内容を返却する

ネットワークエラーによる再試行で冪等性を保証する

概要: クライアントがリクエストを送信したが、ネットワークエラーによってレスポンスが返らず、クライアント側でタイムアウト後に同じリクエストを再送する
期待: リクエストが一度だけ送信された場合と同じ状態になる
アクター: クライアント、システム
メインフロー:
- 1: クライアントが、識別可能な形式でシステムにデータの登録を要求する
- 2: システムは、リクエストを受け取り処理を開始する
- 3: システムは、新しいRevisionを作成する
- 4: ネットワークエラーが発生し、レスポンスがクライアントに到達しない
- 5: クライアントがタイムアウトし、同じ内容で再度リクエストを送信する
- 6: システムは、該当するリクエストが既に処理されていることを認識する
- 7: システムは、既に登録済みのRevisionをクライアントに返却する（新たな登録は行わない）

データの内容は同じだが異なる親Revisionに対して登録する

概要: データの内容は同じだが、異なる親Revisionに対して登録要求が届く
期待: 各要求は異なるものとして扱われ、別のRevisionが作成される
アクター: プロセスA、プロセスB
メインフロー:
- 1: プロセスAが、親Revision-1を指定してデータを登録する
- 2: システムは、(親Revision-1, データ) に対応するRevisionを作成する
- 3: プロセスBが、親Revision-2を指定して同じデータを登録する
- 4: システムは、これら2つのリクエストが異なることを認識する（親が異なるため）
- 5: システムは、(親Revision-2, データ) に対応する別のRevisionを作成する（二重登録ではなく、論理的に異なる履歴）

複数の言語で実装されたクライアントからのリクエストを処理する

概要：Go、Python、JavaScript など複数の言語でクライアントが実装される。システム全体で、同じ(親Revision, データ)に対しては同じ識別キーが割り当たる必要がある
期待: 実装言語に関わらず、同じ仕様に従えば同じキーが生成される
アクター：言語Aで実装されたクライアント、言語Bで実装されたクライアント、サーバー
メインフロー:
- 1: 言語Aのクライアントが、ある仕様に基づいて識別キーを生成する
- 2: 言語Bのクライアントが、同じ仕様に基づいて、同じ(親Revision, データ)に対して識別キーを生成する

運用時のユースケース

識別キー計算仕様を変更する

概要: 運用中にセキュリティ向上などの理由で、識別キーの計算方法（例：ハッシュアルゴリズム）を変更する
期待: 全ての識別キー計算方法を更新できる
前提: デプロイによるコンテナ入れ替え時の新旧クライアント混在の影響は考えない
識別キーをクライアント側で生成する場合:
- アクター: システム管理者、クライアントAの開発者、クライアントBの開発者
- メインフロー:
  - 1: システム管理者は、クライアントAの開発者とクライアントBの開発者に対して識別キーの計算方法の更新を要求する
  - 2: クライアントAの開発者は、クライアントAの識別キー計算方法を更新する
  - 3: クライアントAの開発者は、システムに対して新しいクライアントAのデプロイを要求する
  - 4: システムは、新しいクライアントAをデプロイする
  - 5: クライアントBの開発者は、クライアントBの識別キー計算方法を更新する
  - 6: クライアントBの開発者は、システムに対して新しいクライアントAのデプロイを要求する
  - 7: システムは、新しいクライアントBをデプロイする
識別キーをサーバー側で生成する場合:
- アクター: システム管理者、サーバー開発者
- メインフロー:
  - 1: システム管理者は、サーバー開発者に対して識別キーの計算方法の更新を要求する
  - 2: サーバー開発者は、サーバー内における識別キー計算方法を更新する
  - 3: サーバー開発者は、システムに対して新しいサーバーのデプロイを要求する
  - 4: システムは、新しいサーバーをデプロイする

複数の識別キー計算仕様に対応する

概要: 運用中にセキュリティ向上などの理由で、識別キーの計算方法（例：ハッシュアルゴリズム）を変更する必要が出た場合、システムが円滑に移行できる
前提: クライアントの実装言語は一つ（組み合わせ爆発回避のため）
期待: 計画的な移行により、冪等性を失わずに仕様を変更できる
識別キーをクライアント側で生成する場合:
- サーバーメンテナンス（停止）期間を設けない場合:
  - 前提: クライアントの識別キーの計算方法は実装済みで、デプロイ待ちの状態
  - アクター: サーバー開発者、サーバー、クライアント開発者、エンドユーザーA、エンドユーザーB、ハッシュアルゴリズムAを使う古いクライアント、ハッシュアルゴリズムBを使う新しいクライアント、
  - メインフロー:
    - 1: サーバー開発者は、新旧2種類のハッシュアルゴリズムに対応するようにサーバを変更する
    - 2: サーバー開発者は、システムに対して新しいサーバーのデプロイを要求する
    - 3: システムは、新しいサーバーをデプロイする
    - 4: サーバー開発者は、クライアント開発者に識別キーの計算方法を更新したクライアントをデプロイしても良い旨を連絡する
    - 5: クライアント開発者は、システムに対して識別キーの計算方法を更新したクライアントのデプロイを要求する
    - 6: システムは、クライアントを入れ替え始める
    - 7: エンドユーザーAが、システムに対してデータの登録を要求する
    - 8: システムは、エンドユーザーAの要求を新しいクライアントに振り分ける
    - 9: 新しいクライアントは、サーバーに対してデータの登録を要求する
    - 10: サーバーは新しいクライアントからのデータを永続化し、永続化が成功した旨のメッセージを新しいクライアントに返却する
    - 11: エンドユーザーAは、データが登録されたことを確認する
    - 12: エンドユーザーBが、システムに対してエンドユーザーAと同一の内容で登録要求する
    - 13: システムは、エンドユーザーBの要求を古いクライアントに振り分ける
    - 14: 古いクライアントは、サーバーに対してデータの登録を要求する
    - 15: サーバーは、古いクライアントからの要求内容が処理済みの要求と同一と判定し、新しいクライアントに返却したものと同じメッセージを古いクライアントに返却する
    - 16: エンドユーザーBは、データが登録されたことを確認する
    - 17: システムは、クライアントの入れ替えを完了する
- サーバーメンテナンス（停止）期間を設ける場合:
  - アクター: サーバー開発者、クライアント開発者
  - メインフロー:
    - 1: サーバー開発者は、システムに対してサーバーの停止を要求する
    - 2: システムは、サーバーを停止する
    - 4: サーバー開発者は、クライアント開発者に識別キーの計算方法を更新したクライアントをデプロイしても良い旨を連絡する
    - 5: クライアント開発者は、システムに対して識別キーの計算方法を更新したクライアントのデプロイを要求する
    - 6: システムは、クライアントを入れ替え始める
    - 7: システムは、クライアントの入れ替えを完了する
    - 8: クライアント開発者は、サーバー開発者に対してクライアントのデプロイが完了した旨を連絡する
    - 9: サーバー開発者はシステムに対してサーバーの再稼働を要求する
    - 10: システムは、サーバーを再稼働させる
識別キーをサーバー側で生成する場合:
- メインフロー:
  - 1: サーバー開発者は、サーバー内の識別キー計算方法を更新する
  - 2: サーバー開発者は、識別キーの計算方法が更新されたサーバーのデプロイをシステムに要求する
  - 3: システムは新しいサーバーをデプロイする

冪等性キーの生成場所と等値性の判定場所の決定

上で洗い出したユースケースをもとに、冪等性キーの生成場所と等値性の判定場所について考えていく。

冪等性キーの生成場所について、サーバー側・クライアント側それぞれを選択した場合のメリット・デメリットは下記の通り:

サーバー側で生成した場合
- pros:
  - 冪等性キーの生成ロジックの更新などの運用タスクがサーバー側だけで完結する✓
- cons:
  - 実際には等値と判定されるペイロードも、クライアント側で冪等処理されずサーバーにリクエストされる✗
    - 同値のペイロードが大量にリクエストされた場合にDoSとなりうる
      - 緩和条件:
        
        エンドポイントをprivateに保った場合
        
        リクエスト数が少ない場合
クライアント側で生成した場合
- pros:
  - 同値のペイロードに対する処理を、サーバーにリクエストすることなくクライアント側で完結させられる（キャッシュを保持する場合）✓
- cons:
  - 冪等性キーの生成ロジックやライブラリを更新する場合、クライアントの種数ぶんの更新タスクが発生する✗
    - クライアントの実装言語が複数ある場合、運用工数はさらに大きくなる
    - 緩和条件:
      - 冪等性キーの生成ロジックを共通サービスから取得した場合
        
        費用対効果が見合わない✗

上記から、両方法にはパフォーマンス上および運用上のメリット・デメリットがあることがわかった。

資源評価プラットフォームの性質を考慮すれば、そもそもリクエスト数はそれほど多くならないと考えられるため、サーバー側で生成する方法のデメリットである、リクエスト集中時のスループットの悪さはほとんど無視できると思われる。加えて、将来的には資源計算の入力データだけでなく、出力を保存するユースケースも考えうる: つまりクライアント種が増える可能性も考えれば、サーバーで生成する方法の運用上のメリットが重要となる。もちろん、出力を保存するサービスを専用の新サービスとして開発する構成も考えうるが、data-registryはその名前が示すように既に充分抽象化されているように思う。

上記を考え併せて、現時点では、冪等性キーはサーバー側で生成する方法を選ぶことにする。

冪等性キーがサーバー側で生成されるとなれば、等値性判定もサーバー側に集約するのが自然だろう。

まとめ

本記事では、前回の反省を活かして必要十分にまとめられたように思う。

今回の主役であった冪等性については、過去記事の時点でシステム要件 SR005 として定義してあった:

SR005: 同一の登録要求識別子を持つ登録要求に対しては同一の結果を返し、新たな版を重複して作成してはならない

本記事で下した冪等性キーの生成や等値性判定を行う場所についての意思決定は既存の SR005 には反映されないものの、アーキテクチャに関する意思決定としてdata-registryのADRとした。

現時点におけるdata-registry開発の進捗はこんな感じ:

API契約を書く
ルーティングの動作確認
db セットアップ
リポジトリ・ハンドラの実装
API基本設計
Revision生成ロジックの設計
- 等値性の定義
- 冪等性キー生成場所と等値性判定の場所の決定
- 冪等処理の設計
データベース設計
リファクタリング
エラーハンドリングの追加

つづく

（後日追記）

同じデータを別名で登録するユースケースを追加したので、SR015: 同じデータを別名で登録する要求は異なる要求として扱う を追加した。

すると、等値性の定義は下記のようになる:

等値とみなすリクエスト = hash(parentRevisionId, name, hash(data))が同じリクエスト

補足記事 "PfEingのアプローチで働こう"

Fri, 04 Sep 2026 00:00:00 +0900

これはなに

下記の口頭発表に対する補足記事である。

演題: “PfEingのアプローチで働こう”
イベント名: 【3-shake × enechain】SRE Tech Talk #15
日時: 2026年9月4日
場所: 株式会社スリーシェイク（東京, 銀座）

この記事では、時間の制約から口頭発表には含められなかった情報を補足として紹介する。

発表資料はこちら:

スライド各ページの補足

（タイトル）

本発表で話したのは「PfEingアプローチ」ではない。これでは、私が新しい用語を考え出したことになってしまう。

あくまでも「PfEingのアプローチ」だ。

「プラットフォームエンジニアリング」はスライド上では幅を取りすぎるので “PfEing” で統一した。視覚上は短くなったが、読みは同じなので噛みそうなのは変わらない。

（自己紹介）

サイボウズが提供しているキントーン（kintone, Kintone）というサービスは、単一（というと語弊があるが）のアプリケーションソースコードを国内向け（cybozu.com）・国外向け（kintone.com）二つの基盤で動かすことでエンドユーザーに提供されている。

ちなみに、キントーンのアルファベット表記は、国内向けでは小文字始まりのkintoneなのに対し、海外向けではKintone。

私のチームはkintone.comのプラットフォームを開発・運用しているプラットフォームチームで、社内では通称Yakumoチームと呼ばれている。

10年近い歴史を持つチームなので、記事の中には古くなっているものもあるが、サイボウズのテックブログを “Yakumo” カテゴリで検索すると技術記事がヒットする。

名前の由来をふくむ、Yakumoチーム自体については下の記事にまとまっている。

kintone.com プラットフォームを提供 ~ われら Yakumo にござる | blog.cybozu.io

https://blog.cybozu.io/entry/2026/07/23/100000

「やっていること」

本発表はプラットフォームエンジニアリング的な働き方について述べたものだが、別のアプローチの働き方をした経験があるので前職の例と対比した。

DevOpsをチーム名に冠すること自体についてはここには書ききれないので、別の機会に書こうと思う。

「PfEingチームの働き方」

発表には含められなかったが、最近はプラットフォームエンジニアリングに関して、下記のテーマについて考えている:

PfEingというアプローチそれ自体
プラットフォームの “optional” という特性と、それが満たされないときに起こること
一応の運用が効果計測を目的とした計装と社内の信頼残高との関係
責務境界のあるべき姿とストリームアラインドチームの負担増

上記のうち、「PfEingというアプローチ」に関して、LTサイズに切り出せるメッセージが見つかったので本発表を作った。

本スライドに示したのは、本発表が特に影響を受けた下記の記事・書籍である:

“What I Talk About When I Talk About Platforms” Bottcher (2018)
“CNCF Platforms White Paper”
“How Platform Engineering Works” McElligott (2023)
『プラットフォームエンジニアリング』Fournier & Nowland (2025) オライリー・ジャパン
『実践プラットフォームエンジニアリング』Chankramath et al. (2026) マイナビブックス

「損益分岐点がある」

こんにち（2026年）では、「プラットフォームエンジニアリング」という言葉が定着しつつあるため、このデシジョンツリーを使うなどして「プラットフォームエンジニアリングをするかどうか」というメタ認知を持ってプラットフォームチームを立ち上げられる。プラットフォームチームにとって（もちろん組織全体にとって）、これは本当に大きい利点だ。

この言葉がなかった頃から、形を変えながら続いてきたプラットフォームチームでは、プラットフォームとして必ずしも適切とはいえない責務を抱えていることがあると思う。

「常に必要な自問」

「自分たちはPfEingできているか？」

現実世界でちゃんとPfEingするのは本当に難しいので「できているか」を強調してある。

プラットフォームエンジニアは、自分達の働き方について、本当に自覚的になる必要がある。プラットフォームエンジニアの場合、他チーム¹から見て「いい仕事」をしているように見えても、プラットフォームエンジニアリング的に誤ったアプローチで働いてしまうというケースは、いくらでも生じうる。顧客の満足が必ずしも

宿命的にROIが重要

これには引用があるわけではなく、発表において言葉の簡潔さとパワーを得るためにこのフレーズを使った。

といっても、プラットフォームエンジニアリングについて色々な情報を読んでいれば意味するところは理解いただけるのではないかと思う。

関連する記述を具体的に揚げるとすれば、『プラットフォームエンジニアリング』では、プラットフォームチームは、より大きいものを管理するために自チームのサイズを大きくすることに慎重になる必要があることを指摘している（13.3「成長をコントロールすることによる複雑性の管理」）。これは単純にROIの分母が大きくなってしまうだけではなく、働き方の質を変えるための吟味の機会を失うことも意味するからだ。

「PfEingのアプローチ」

どこから取ろうがエッセンスは変わらないが、ここでは代表としてCNCFのPlatforms White Paperからの引用を示した。このドキュメントは短いが、読むたびに新しいテーマについて考えるきっかけが得られるので、私は定期的に読むようにしている。

ちなみに現時点のPlatforms White Paperは、雑にキーワード検索するとApp Delivery TAG版の古いドキュメントがヒットしがち。現行のドキュメントはcloudnativeplatforms.comのこちら。

「気を抜くとかんたんに外れうる」

プラットフォームエンジニアリングチームがどう働くべきチームなのかを、組織の中で最もよく理解しているのはプラットフォームチーム自身だ。そもそも「依頼」という言葉自体、危険な香りがする。プラットフォームチームとしては、TicketOps的な慣習をアンラーニングし、顧客チームとの関わり方自体も組織として成熟させていく必要がある。『チームトポロジー』の用語で言うならば、ここで言っているのは「顧客チームとの “コラボレーションモード” を “X-as-a-Service” に変えていけ」という話ではない。新しいケイパビリティの探索フェーズでは、コラボレーションモードが必要になる。ここでは「依頼を受けて作る」という働き方を、雑に「コラボレーションモード」と呼んだりはするな、という意味で言っている。

余談だが、参考リンク先の「Terraformスタータキット」のアンチパターンの例²については、もしスタータキットのモジュール配布だけをやっていた場合には少しマシになる³という理解。

「どうしても断れない依頼」

このケースは、最初からプラットフォームチームとして設計されて立ち上がった、新しいプラットフォームチームでは起こりにくいのかもしれない。

一方で、形を変えながら続いてきたプラットフォームチームには、このパターンはよく発生するのではないだろうか。

「…現実世界はいろいろあるけど」

プラットフォームエンジニアリングは全体最適を追求する働き方だ。全体最適は組織にとって善きものだが、それを推進する取組みもまた善きものと見られるかどうかは、他のタスクとの比重に因っている。他チームに預けた信頼残高も関わってくる。

謝辞

発表の機会を提供してくださったスリーシェイクさん、enechainさん、ありがとうございました。

「他チーム」とはもちろん、プラットフォームエンジニアリングについての解像度が低いチームのことだ。当然、他のプラットフォームチームの目はごまかせない ↩︎
ここでいうアンチパターンとは「プラットフォームチームとしての」アンチパターンのこと。状況に応じた方法を選ぶことが重要 ↩︎
マシになるとは、プラットフォームエンジニアリング的な働き方にやや近づく、と言う意味 ↩︎

『実践プラットフォームエンジニアリング』を読んだ

Sat, 29 Aug 2026 00:00:00 +0900

Effective Platform Engineeringの邦訳版が出たので読んでみた。

実践プラットフォームエンジニアリング─開発者体験を加速するセルフサービス基盤の設計と構築

執筆: Ajay Chankramath, Nic Cheneweth, Bryan Oliver, Sean Alvarez
翻訳: 株式会社スリーシェイク（元内柊也、小池玲斗、木曽和則、下村俊貴）
マイナビブックス、2026年

私が読んだのはPDF板。なお本書は会社のSLP（Self Learning Program）という仕組みを利用して購入した。

どんな本か

こんにち、プラットフォームエンジニアリングのマインドセットは言語化され、例えば “CNCF Platforms White Paper” などで参照可能になっている一方で、それらを具体的にどのように実現するかについては、まだまだ情報は充分とはいえない。本書は、コンサルタントとしてエンジニアリングプラットフォームの実装に関わり、多くの場数を踏んだ著者らによるものなのでこの “how” の部分が手厚く解説されている。ちなみに著者陣のキャリアは、4人全員がThoughtworksあるいはBrillioにあり、これはつまりプラットフォームエンジニアリングにとって重要な要素であるスケール性を扱った経験が豊富ということを意味する。また、特定のプラットフォームプロダクトのベンダー企業ではないというところも、実践形式の書籍として良い点といえる。

本書の他に、プラットフォームエンジニアリングに関して体系的に読める別の書籍としてはオライリージャパンの『プラットフォームエンジニアリング』¹もあるが、本書のほうが後発なだけあって現時点におけるプラットフォームエンジニアリングの業界の標準が反映されている。 2026年時点において、プラットフォームエンジニアリングについて知りたい人がまず読むならば、あちらの本よりも本書を先に読むと良さそう。本書で「どんな世界観をどう実装するか」を理解したあと、「それを社内（政治的制約がある環境）でどう推進するか」について『プラットフォームエンジニアリング』を読みながら考えてみるとよい。

また本書はプラットフォームエンジニアリングの定義に成功指標の計測も含めており、オブザーバービリティを第一級市民として扱っているところも特徴といえる。

個人的に目に止まったところ

第1章プラットフォームエンジニアリングとは何か

プラットフォームはDevOpsにとどまらない（p.4）

本節で書かれている “DevOps” の認識に同意しかねる部分がある。コメントの分量が膨らんでしまいそうなので、別の記事で書くことにする。

第2章ソフトウェア・デファインドのプロダクトとアーキテクチャ

1年後にプラットフォームがどう使われるかを予測するのは不可能（p.44）

この解釈は難しいところだと思う。本書は技術選定時にはなるべく少ない機能のものを選ぶことを推奨しているが、だからといってここの記述は「今だけを見て意思決定しろ」という意味ではないはず。チームとして戦略的視点に基づいた動きをしていることは恐らく前提（…そうだよな？）。要はよくよく気をつけろというメッセージと理解した。

それにしても「不可欠だと思われていたケイパビリティが実は不要だった」は肝に命じておきたい。 YAGNIとは昔から言われるが、ここで述べられているのは「あったら良いと思ったが不要だった」ではなく、「不可欠だと思ったが不要だった」だから恐ろしい。要件を考える段になってYAGNIを唱えるのではなく、戦略レベルから注意を払わないとだめということ（難しい）。

ドメイン駆動プラットフォーム設計（p.54）

プラットフォームエンジニアリングの文脈でDDDを強調しているのは本書の一つの特徴。個人的には、ソフトウェア開発ど真ん中のキャリアではないながらも、DDDについては本業とは別に継続的に自己投資してきたので、これまで学んできたことが本書を読んで数年（5年くらい？）のタイムラグを経てつながった感じがある。

スムーズな開発者体験を実現するインフラコスト配賦（p.59）

ここで書かれているスムーズな開発者体験は、顧客チームにインフラのコスト配賦をできている前提。バックオフィスとも連携がとれた組織のレベルが高い話だ。

手動プロセスによる機会損失（p.60）

手動プロセスが機会損失につながることは誰でも知っているが、コストや効果の計測を第一級市民として扱う本書では、機会損失は言葉だけでなく実際に算出する値としての意味を持っている。こういった広い意味でのオブザーバービリティは、短期的な顧客価値につながりづらいので推進が難しいが、裏を返せばオブザーバービリティ確保の先延ばしは、チームが「このプロダクトは（たぶん）顧客の生産性を高めた（んだと思う…）」という状態で働き続けることを意味する。

組織固有のケイパビリティをk8sのAPI拡張でオーケストレーションする（p.62）

自動化はソフトウェアエンジニアリング文化の空気みたいなものだが、オーケストレーション──確実に動き続ける──まで保証できるのはプラットフォームエンジニアリングならではのアプローチだと思う。

第3章計測で導くプラットフォームエンジニアリングの成功

エンジニアリングプラットフォーム構築のデシジョンツリー（p.70）

図3.2のデシジョンツリーは、プラットフォーム構築がプラスになるかどうかの境界フェーズにある組織にとってはなかなか役立ちそう。

プラットフォーム価値モデリング（p.77）

プラットフォームチームの取組みが組織のバリューストリームから遠ざかることについて、これまでにもアンチパターンとして認識されてきた（例）。本書が「プラットフォーム価値モデリング」としてモデル化したことで、世のプラットフォームチームは「アンチパターンに陥らないようにする」という具体性を欠いた否定形ではなく「プラットフォーム価値モデリングする」と能動態で考えられるようになった。これは一種のケイパビリティだと思う。

パフォーマンスメトリクス | オンボーディング時間（p.86）

社内プラットフォームだからといって認証をおろそかにすると、こういったオブザーバービリティ面でツケが回ってくる。

エンジニアリングプラットフォームのプロダクトドメイン（p.91）

図3.8は抽象的だが、ここで表されているものは、AWS上にEKSで環境を構築しているチームならば普通に使っているリソースを、本書の基準で分類したもの。この8つの分類は初見時にはあまりしっくりこないかもしれないが、“6.4 クラウド管理ID”（p.193）以降で登場するそれぞれの分類の解説を読めば、その合理性がだんだんわかってくる。

第4章ガバナンス・コンプライアンス・信頼

IDプロバイダーソリューション（p.117）

チームの境界で見られがちな「依頼」という協働パターンを撲滅するヒントがある。

第5章進化するオブザーバービリティ

オブザーバービリティの8つのレンズ（p.131）

2026年現在、「オブザーバービリティ」といえば一般にはアプリケーションのオブザーバービリティを指すと思うが、本書ではそれをエンドユーザー（社内の開発者ユーザーのこと）体験を制限するアンチパターンと言い切っている。本書はオブザーバービリティを「エンジニアリング」カテゴリと「ビジネス」カテゴリそれぞれ4つづつの主要8軸に分類し、組織のすみずみまで可観測性がある世界観を提示している。当然、BIツールまで含むので、恐らくすべてプラットフォームチームが担当するわけではないだろう。もしくは、いま「データエンジニアリングチーム」と呼ばれるものもプラットフォーム組織配下のチームとして考えているのかもしれない。

「ビジネス」カテゴリのオブザーバビリティについて

（2026/09/06追記） > 当然、BIツールまで含むので、恐らくすべてプラットフォームチームが担当するわけではないだろう。

ここは誤解していた。本書が言っているのはBIツールではなく、やはりオブザーバビリティツールと思われる。『オブザーバビリティ・エンジニアリング²』に、これのヒントとなる記述があった。そちらの本の内容の繰り返しになってしまうのでここには書かないが、「20.3 "オブザーバビリティツールとビジネスインテリジェンスツールの使い分け"」のあたり。最近のBIツールは対話的クエリ能力も向上しているので、オブザーバビリティツールとBIツールは重なる部分が広くなってきているとは思うが、そもそもの設計思想が異なることを認識し直した。

第6章ソフトウェア・デファインドなエンジニアリングプラットフォームの構築

名前空間レベルのパイプライン（p.170）

ここで解説されているpreviewクラスタはおもしろい。社内顧客を抱えるチームとして、インフラのメンテを安心して当てるのに合理的な構成となっている。

第7章プラットフォームコントロールプレーンの基礎

クラウドアカウントのベースライン（p.214）

ここに差し掛かると、本書がこの「クラウドアカウントベースライン」を、前章で解説された「クラウド管理ID」とは異なるレイヤーのリソースとして認識していることを理解できる。本来、AWSのリソースモデルの構造としては「アカウント」の下に「IAMロール」があるわけだが、本書の認知モデルではまず「クラウド管理ID（IAMロールが含まれる）」があり、その上に「クラウドアカウントベースライン（AWSアカウントを指す）」が載っている。もちろん、AWSのリソースモデルとは異なるこの認知モデルが常に最高なわけはないが、複数アカウントの運用そのものが業務ドメインの中心にあるプラットフォームエンジニアリングの文脈では、なるほどこの整理は合理的だ。

ただ環境を動かすだけなら誰にでもできる。きれいに運用するのが難しい。こうやって見せてもらえれば腹落ちするのだが、この整理は自分では思いつけそうにない。ここはなかなか勉強になった。

第8章コントロールプレーンのサービスとエクステンション

プラットフォームエンジニアリングとDevOpsのアプローチの違い（p.317）

「スターターキット」のプラクティスを例に、DevOpsとプラットフォームエンジニアリングの違いが解説されている。この解像度での解説は本書ならではで、両者は全く違うことがわかる。特にプラットフォームエンジニアリングをする立場にあるならば、きちんと理解しておく必要がある。

第9章スケールを支えるアーキテクチャの変更

アジャイルプラクティスの導入（p.358）

『プラットフォームエンジニアリング』はプラットフォームチームがアジャイルな進め方をすることにかなり注意深い態度だったが、本書はけっこうアジャイル派な印象。

第10章プラットフォームプロダクトの進化

内部開発者プラットフォーム（IDP）と開発者ポータルの比較（p.378）

名前からしてそもそも紛らわしいので、ここは多くの読者が注意深く読みそう。解説されてみれば、両者は確かに全く異なるし、はっきり使い分ける必要がある。

理解しにくかった箇所の個人的メモ

p.10

3つの概念は互いに依存し合っています

“4つの概念” だろうか。

余談だが、図1.3のような循環を表す模式図は、矢印を曲線にするだけで飛躍的に理解しやすくなる。

p.20

ハンドオフ: 仕事の受け渡しのこと

p.21

図1.8

SAST: static application security testing
DAST: dynamic application security testing

p.29

セキュリティステークホルダーが企業認証基準を、(1) 内部認証の単一の信頼できるソースを要求し、(2) 内部実装をOAuth 2.0 フレームワークに基づくものと定義する場合です

これは恐らく下記の意味だと思う。

セキュリティステークホルダーが企業認証基準を下記のように定義する場合です。

(1) 内部認証の単一の信頼できるソースを要求するもの
(2) 内部実装をOAuth 2.0 フレームワークに基づくもの

p.33

成功は、独立してドメインに専念する開発チームから生まれます。各チームは自分たちのドメインに固有のアイデアを試行します。計測可能な体験と価値を生み出すためにソフトウェアを構築してテストします。そして、ソフトウェアを顧客にリリースし、質の高いユーザー体験を確保しながら結果を注視して管理します

これは恐らく下記の意味だと思う。

成功は、独立してドメインに専念するアプリケーション開発チームから生まれます。各チームは自分たちのドメインに固有のアイデアを試行します。計測可能な体験と価値を生み出すためにソフトウェアを構築してテストします。そして、ソフトウェアを社外顧客にリリースし、質の高いユーザー体験を確保しながら結果を注視して管理します

p.80

「認知負荷の増加は10%以内」はどう計測するんだろう。 p.82には「認知負荷の影響を評価する体系的な手法が存在します」とだけ書いてある。認知心理学の分野では確立されていたりするんだろうか。

ちなみに、複数のプラットフォームプロダクトが時間差でリリースされた場合、認知負荷の変化がどのプロダクトによるものなのかわからなくなりそう。成功指標の計測を徹底している組織では、同じ認知コンテキストに影響する変更が一つづつになるよう、リリース管理するんだろうか？

p.89 表3.1, 3.2

これらの情報は表で表してはいけない（同じ行間を比較したくなる）。実査には下記のように、単なるリストで表示するのが正しい。

表3.1

計画
- 開発者の関与
- 顧客フィードバックループ
- …
設計
コード
ビルド

表3.2

テスト
- テストの種類
- テスト自動化
- …
リリース
監視
運用

p.138

5.2.1 エンドユーザーのアクセス体験

エンドユーザーとは、プラットフォームサービスとしてのオブザーバービリティ機能を利用する社内開発者ユーザーのこと。個人的には「エンド」と付くと本当の末端（会社が提供しているプロダクトのユーザー）をイメージしてしまうので紛らわしく感じる。

p.139

5.2.2 顧客データの自動収集

ここの「顧客」とは社内開発者ユーザーのことだと思う。判断根拠は、p.140に「アプリケーションチームは、自分たちのデータがどのように収集され保存されるかという内部の仕組みを気にせず済みます」とあること。よって「自分たちのデータ」とは「自分たちが所有するデータ」の意味であって、「自分たちが生成したデータ」ではないはず。従って、実際にはデータの中身は会社が提供しているサービスのユーザーのアクセスデータなどが含まれているはず。

p.186 図6.14

誤: my-orb/name of job-in-orb
正: my-orb/name-of-command-in-orb

p.193 図6.16

「エンジニアリングプラットフォームドメイン」が指しているのはたぶん「EPステートアカウント」配下なんだろう。「EPステートアカウント」は「Engineering Platformステートアカウント」と思われる。「EP非本番アカウント」と「EP本番アカウント」はプラットフォームの社内顧客が使うんだと思う。「domain-nameアカウント」はどこかのチームが何かの用途に使っているアカウントとの関係を示しているだけで、これらの解説は恐らく本書には出て来ていない。

p.214

このドメインは、同じくクラウドアカウントレベルの設定を扱う点で前のドメインと似ている

これは下記の意味:

「この概念は、同じくクラウドアカウントレベルの設定を扱う点で、前章（6.4）で説明したクラウド管理IDと似ている」

p.275

エンジニアリングプラットフォームプロダクトのリーダー層に直接属さないチームも含めて作業を分担せざるを得ない圧力もかかる

これは恐らく下記の意味:

「直接属さないチームも含めて作業を分担せざるを得ない圧力が、エンジニアリングプラットフォームプロダクトチームのリーダー層にかかる」

両者の違いをもう一度見てみましょう

「もう一度」とあるが初出と思われる。

p.276

エクステンション

私は「サービス」「エクステンション」という分類にあまり馴染みがなかったが、本書が示す分類基準でいえば、例えばCrossplaneは恐らく「エクステンション」に分類されるのだろう。

p.340 図9.11

図中に見慣れない黒い点があるが…ストリームイベントを示している？

p.344 図9.15

2本の垂直線の太さが同じだが、恐らく左はy軸、右はリリースイベントがあったx軸上の位置を示すものと思われる。

所感

本書を読むと、自チームでも適用 or 参考にしたくなるものが何かしら見つかるのではないかと思う。

プラットフォームエンジニアリング関連のカンファレンス

Sat, 22 Aug 2026 00:00:00 +0900

今後開催されるプラットフォームエンジニアリング関連カンファレンスのスケジュールと過去実績の統計。

内側が国内、外側が国外で開催されるカンファレンス。

密度曲線: 開催日およびCfPの過去実績（前後7日の移動平均）
点: 今後の開催日およびCfP締切。黄枠の青点はCfP未クローズの開催日

開催日 CFP締切

イベント	CfP締切	開催時期
GopherCon 2026 GoDeveloper Experience
Go Conference 2026 GoDeveloper Experience
Platform Engineering Kaigi 2026 Platform EngineeringDeveloper Experience
SREcon EMEA 2026 SREReliabilityObservability
KubeCon + CloudNativeCon North America 2026 KubernetesCloud NativePlatform EngineeringObservability
Kotlin Fest 2026 KotlinJVMDeveloper Experience
CloudNative Days Winter 2026 Cloud NativePlatform Engineering
SRE Kaigi 2027 SRE	未定
SRE NEXT 2027 SREObservability	未定
表示するデータがありません

Organizational efficiencyとProduct and feature deliveryは何が違うのか

Wed, 12 Aug 2026 00:00:00 +0900

“CNCF Platforms White Paper” に紛らわしい箇所があったが、自分なりに理解できた気がするので、思考の整理を兼ねて言語化しておく。

扱うテーマは “How to measure the success of platforms”: プラットフォームの成功を客観的・定量的に計測するためのガイドラインの部分¹。

ここで推奨されている計測対象は、下記の3カテゴリに分かれている。

カテゴリ	指標
User satisfaction and productivity	アクティブユーザーと定着率、NPS、SPACE
Organizational efficiency	各種のレイテンシ（後述）
Product and feature delivery	DORA の（旧）4指標²

当初、第二カテゴリと第三カテゴリの違いがいまいち腑に落ちなかった。 “Organizational efficiency” も “Product and feature delivery” も、要は効率に関する計測として一括りにできるようにも思えてしまい、別カテゴリとされる理由がわからなかった。

それぞれについて少し注意深く読んでみると、両者の違いは、「計測しているイベントの性質」および「誰が誰を待たせているか」にあるような気がする。

“Product and feature delivery” で計測するDORAの4指標はいずれも、反復的なデリバリー性能を示すものだ:

Deployment Frequency
Lead Time for Changes
Change Failure Rate
Time to Restore Service

一方で、“Organizational efficiency” とされる下記の3指標は、いずれも何かが初めて実現されるまでの時間に関するメトリクスであることがわかる:

指標	観点	支配的な要因
Latency from request to fulfillment of a service or capability, such as a database or test environment	開発リソース	セルフサービス化の度合い
Latency to build and deploy a brand new service into production	サービス	ゴールデンパスとテンプレートの整備度
Time for a new user to submit their first code changes to their product	ヒト	ドキュメント・権限・開発環境の整備度

これらの理解をふまえると、両カテゴリは概ね下記のように表現しても良いと思う:

Organizational efficiency: プラットフォームが顧客である開発者を待たせている時間³
Product and feature delivery: 組織がエンドユーザーを待たせている時間

それぞれを計測した場合の効果については、たぶん下記のような整理になるのではと思う:

程度の差ではあるが、プラットフォームチームの取組みの効果を純粋に見たいのであれば、実装やレビューの所要時間の影響を受ける “Product and feature delivery” に比べて、“Organizational efficiency” のほうが適しているだろう
ただし、プラットフォームチームの取組みは組織としてのバリューストリームに関わるものになっていないとまずい。原文にもあるように “Product and feature delivery” のほうが “true measure of the success of a platform” だ。ここを外してしまうと、プラットフォームが “an expense quite disconnected from their primary value streams” と見なされがちになる⁴

本記事を書きながら、2年ほど前に組織メトリクスに関する一過性ブーム的な盛り上がりがあったことを思い出していた。最近は落ち着いてきた（飽きる企業が出てきた？）ように思うが、当時は組織メトリクスに対して、計測するだけで何かが起こるかのような、過度の期待があったのではないかと想像する。組織メトリクスは、それぞれのカテゴリが何を映しているのかを踏まえた上で、必要な情報を得るための普通の手段として運用したらいい。

執筆時点では “platform engineering white paper” で検索すると、旧サイトのドキュメント（新サイトのv1相当）がトップに出てきてしまう。本記事の大半はこのあたりの事情を知らずに旧サイトのv1を読んで書いたのだが、執筆時点の最新版であるv1.1においても “How to measure the success of platforms” の内容は同一だった ↩︎
原文が参照しているDORAの指標は2019年ごろのものなので（原文で参照されているのはこちらだが、内容的にはこちらのほうが適当に思える）、“time to restore service” の改称や第5メトリクスの追加・分類軸の変更（ref）は反映されていない。これらは次の版で取り込まれるのかもしれない ↩︎
もっとも、二つ目の “Latency to build and deploy a brand new service into production” と三つ目の “Time for a new user to submit their first code changes to their product"については、実装やコードレビューの所要時間も含まれうる ↩︎
ちなみに、プラットフォームの利用は個人・チーム・組織の性能を向上させる一方で、“throughput” と “stability” の各指標を低下させることが報告されている（ref） ↩︎

Model the Data, Not the Interface

Sat, 08 Aug 2026 00:00:00 +0900

How a simple YAML data model let me add a client-facing CMS without touching the existing implementation.

The Story

A client asked for a profile page featuring his career timeline. Straightforward request. I built it, deployed it, and moved on.

Months later, he came back with a new request: he wanted to update the timeline himself—to add new positions and modify past entries.

Until then, I had been making those changes for him. Giving him direct access to the data wasn’t an option either: he was a non-technical user, and GitHub access was deliberately off the table.

At first glance, adding a content management interface sounded like a change that might ripple through the existing implementation.

It didn’t.

The reason went back to a small design decision I had made months earlier, before a CMS was even a consideration.

The Initial Design Choice: YAML Over Markdown

When I first built the profile page, I didn’t hard-code the timeline into HTML, but I didn’t put it in Markdown either. I started by asking what kind of content a career timeline actually is.

A career history isn’t really a document. It’s structured data: a collection of dates, each associated with one or more events. So I represented it that way:

# data/timeline.yml
entries:
  - date: 2020
    events:
      - Joined the neighborhood cat council
      - Took responsibility for afternoon naps
  - date: 2021
    events:
      - Became a boss cat
      - Led a team of 5 cats

I then rendered the data with Hugo:

<!-- layouts/shortcodes/timeline.html -->
<dl class="timeline">
{{ range .Site.Data.timeline.entries }}
    <div class="timeline-entry">
        <dt class="timeline-date">{{ .date }}</dt>
        <div class="timeline-events">
            {{ range .events }}
                <dd class="timeline-event">{{ . }}</dd>
            {{ end }}
        </div>
    </div>
{{ end }}
</dl>

This kept both the data structure and the implementation simple.

The career timeline rendered from the YAML data

Why YAML Instead of Markdown?

Many static-site workflows are Markdown-first, and for good reason. Markdown is excellent for prose: articles, documentation, and other document-shaped content. But not all content is document-shaped.

A career timeline is fundamentally a collection of structured records: dates with associated events. The same is often true of navigation menus, pricing tables, office locations, product specifications, and similar content.

Representing those structures as Markdown would mean making the data fit the document format rather than choosing a format that fits the data. For the timeline, YAML was the more natural representation.

I wasn’t thinking about CMS support at this point, nor was I trying to make the architecture extensible. I was simply representing the content in the form that best matched its nature.

That distinction became useful later.

The Requirement Change

Months later, the client wanted to manage his own career history. The new editing workflow had a few constraints:

It had to work for a non-technical user.
GitHub access was off the table.
Inputs needed validation: a year should be a number, and an entry should contain at least one event.
Changes had to be committed and deployed automatically.

The existing YAML files were already a perfectly good representation of the content. The problem wasn’t the data model; the problem was that the only interface for changing it was a text editor and Git.

So instead of replacing the existing content model, I added another interface to it.

The Solution: Add an Interface, Not a New Data Model

I used Decap CMS, a Git-based CMS that can map an editing UI onto files stored in a repository.

The configuration for the timeline looked roughly like this:

# static/admin/config.yml
- label: "Profile"
  name: "profile"
  files:
    - label: "Career History"
      name: "timeline_data"
      file: "data/timeline.yml"
      fields:
        - label: "Career entries"
          name: "entries"
          widget: "list"
          fields:
            - label: "Year"
              name: "date"
              widget: "number"
              value_type: "int"
              min: 1980
              max: 2050

            - label: "Events"
              name: "events"
              widget: "list"
              field:
                name: "event"
                widget: "string"
              min: 1

Decap CMS could now present the existing data as a form suitable for the client.

Resources

A minimal working example is available on GitHub, with a live demo deployed on Netlify.

The important part was what I didn’t change.

The YAML structure? ──Unchanged; The Hugo templates? ──Untouched; The site still rendered exactly the same way.

I had simply added a new way to edit the existing data.

Before (top) and after (bottom) adding a CMS: the existing data flow remains unchanged.

No refactor, no breaking changes.

Why So Little Had to Change

What made this work was surprisingly simple: the editing side and the rendering side could depend on the same file-based data model.

File-based integration via a shared data contract

The Hugo templates depend on the structure of the YAML to render the timeline, while the Decap CMS configuration depends on the same structure to provide an editing interface. But the two sides don’t need to know about each other: Decap CMS doesn’t know how Hugo renders the timeline, and Hugo doesn’t know that Decap CMS exists.

They only agree on the shape of the data.

The YAML structure acts as a shared data contract between authoring and publishing. Adding another way to display the same data means writing another consumer of the model; adding another way to edit it means adding another authoring interface. Neither necessarily requires changing the underlying content model.

Of course, if the content itself changes—if a career entry suddenly needs locations, employers, categories, or relationships—the data model should change too. The point isn’t that the model never changes; it’s that adding an interface doesn’t inherently require it to change.

Model the Content for What It Is

What’s interesting to me is that none of this was planned. When I chose YAML, I wasn’t anticipating a CMS. There was no abstraction layer waiting for future requirements, no repository interface, and no elaborate content architecture.

I simply looked at the content and asked:

What is this thing?

The answer was structured data, so I represented it as structured data. That gave the later CMS integration a clean boundary almost for free.

This is different from trying to future-proof a system through speculative abstraction. I didn’t predict the future requirement; I represented the requirement I already had accurately enough that the future requirement fit naturally around it.

This applies beyond career timelines. A blog post or an article is usually document-shaped, making Markdown a natural fit. But a timeline is a collection of records, a navigation menu is a tree, and a pricing table is a collection of products, attributes, and prices. Different kinds of content have different natural structures.

So rather than starting with the tool—

How should I write this in Markdown?

—I find it more useful to start with the content:

What is this content, really?

The representation follows from there. Markdown is often ideal for document-shaped content. YAML, JSON, or another structured store may better represent structured content. Relational or highly dynamic data may belong in a database.

The specific format is secondary. What matters is whether the model reflects the structure of the thing being represented.

Takeaway

Adding CMS support to this site turned out to be surprisingly small—not because I had designed the system for a CMS or anticipated the requirement, and not because I had introduced abstractions to protect against future changes. I had simply modeled a career timeline as what it was: structured data.

When the client later needed an editing interface, Decap CMS could depend on that same model while Hugo continued rendering it exactly as before. The CMS became another interface to the data, rather than a replacement for the architecture.

That experience left me with a simple design heuristic:

Don’t model content around the tool that happens to consume it today. Model it around what the content actually is.

In this case, the flexibility followed naturally.

イミュータブルなデータレジストリの設計とAlloyによる形式検証

Fri, 07 Aug 2026 00:00:00 +0900

前回に引き続き、data-registryサービスを実装していく。今回はdatasetVersionの生成ロジック周りを設計する。

はじめに

データを登録するためのサービスが必要ということがわかったので、下の記事で、データ登録サービス: data-registryの構築に必要なセットアップを終え、ハンドラの実装まで完了した。

データ登録サービスの構築その1 | rindrics.com

https://rindrics.com/articles/stock-assess-data-registry-1/

作業の進捗は下記の通り:

API契約を書く
ルーティングの動作確認
db セットアップ
リポジトリ・ハンドラの実装
datasetVersion生成ロジックの設計
リファクタリング
エラーハンドリングの追加

データセットの生成ロジックは、Alloyでモデル検証しつつ設計する。

要求と要件の整理

正常ケースのレスポンスとして、まずUUID形式のversionを返してほしい旨についてはOpenAPIに既に書いた。

{
  "version": "019f8bff-a5b8-7014-bfc8-41561eaac24c"
}

将来的にはもっと有用なレスポンスを返したほうがよさそうだが、ひとまずの仕様としてシンプルなこの動作について、ロジックを設計したい。

ここで設計するのは、この文字列を何のアルゴリズムで得るかという話ではなく、この値がレスポンスとして返るまでにどんな事項を考慮しないといけないかという話。コンシューマのユースケース支援の観点と、バックエンドサービスとしての堅牢性や処理速度をバランスさせながら考えていく。

要求（Requirements）

仕様を検討するにあたり、data-registryのコンシューマのユースケースを想定し、要求を洗い出したい。こちらの記事で定義したユビキタス言語を使い、要求を次のように整理する:

ID	説明
R001	同一の登録要求に対して、常に同じ応答を返すこと
R002	同一の版に対する取得要求には、常に同じ内容を返すこと
R003	評価データまたはパラメータセットの登録成功後、その版を取得できること
R004	評価データまたはパラメータセットの登録に失敗した場合、コンシューマが失敗を検知できること
R005	登録要求に対して有限時間内に応答すること
R006	評価データ、パラメータセットまたはシナリオを、通常の利用対象から外せること
R007	評価データまたはパラメータセットを修正した場合でも、修正前の版を取得できること
R008	任意の版を指定して取得できること
R009	外部公開済みの版を訂正した場合でも、訂正前の版を追跡できること
R010	アーカイブと、機密情報などを除去するための物理削除を区別できること
R011	評価データおよびパラメータセットの版の履歴を追跡できること

immutableなサービスにしようと意気込んでいたのでR010は当初入れてなかったが、リソースのリビジョン機能をサポートするAPIでは物理削除が必須という記述を読んだので追加した¹。

システム要件（System Requirements）

上で整理した要求から、下記のシステム要件が導かれた:

ID	説明
SR001	各評価データおよびパラメータセットは、版を用いて管理されなければならない
SR002	登録後の版の内容を変更してはならない
SR003	評価データまたはパラメータセットを修正するときは、既存の版を更新せず、新しい版を作成しなければならない
SR004	新しい版は、既存の版を0個または1個参照しなければならない
SR005	同一の登録要求識別子を持つ登録要求に対しては同一の結果を返し、新たな版を重複して作成してはならない
SR006	登録処理が成功した場合、取得APIから登録された版の内容を取得できなければならない
SR007	版を指定した取得要求には、その版に記録された内容を返さなければならない
SR008	評価データおよびパラメータセットは、それぞれ高々1つの最新版を持たなければならない
SR009	新しい版の登録成功後、最新版は新しい版を指さなければならない
SR010	新しい版が登録されても、過去の版を変更または削除してはならない

これらの要件を出発点とし、データ登録機能を提供するバックエンドサービスとしてあるべき姿に照らして、追加で必要な要件をモデル検証であぶり出していく。

モデル検証にはAlloy 6を利用する。動作環境は下記の通り:

macOS 15.6.1（Apple M1 Max）
Alloy Analyzer 6.1.0.20211119T054551

要件を満たすモデルの探索

システム基本構造の定義

data-registryサービスのドメイン構造として、下記を表現することにした:

#	Alloy signature	意味
1	Resource	ユビキタス言語より
2	AnnualAssessment	ユビキタス言語より
3	AssessmentTarget	ユビキタス言語より
4	AssessmentDataRevision	評価データの版
5	ParameterSetRevision	パラメータセットの版
6	Registry	data-registryサービス

その他、Alloyによるシミュレーションを動かすために必要なstutterなどを足して、下記のコードから始めることにする:

commit 46d22f240c3b20868818dcbf6d5b09dba5d161d7
Author: Akira Hayashi <rindrics@gmail.com>
Date:   Thu Jul 30 06:04:25 2026 +0900

    feat: define fundamental model structure

diff --git a/services/data-registry/docs/model.als b/services/data-registry/docs/model.als
new file mode 100644
index 0000000..36a45f9
--- /dev/null
+++ b/services/data-registry/docs/model.als
@@ -0,0 +1,84 @@
+module DataRegistry
+
+/*  ============================================================
+    1. System Requirements
+    ============================================================ */
+// SR001: AssessmentData and ParameterSet, along with their respective versions, must be managed separately.
+// SR002: Each version must be assigned a unique identifier, and the contents must not be modified after registration.
+// SR003: When modifying AssessmentData or ParameterSet, a new version must be created instead of updating the existing version.
+// SR004: A new version must reference exactly zero or one previous version as its source.
+// SR005: For registration requests with identical IdempotencyKey, the same result must be returned without creating duplicate versions.
+// SR006: After successful registration, the registered version must be retrievable via the retrieval API.
+// SR007: Retrieval requests specifying a version must return the contents recorded in that version.
+// SR008: AssessmentData and ParameterSet must each have at most one current version.
+// SR009: After successful registration of a new version, the current version must point to the new version.
+// SR010: Past versions must not be modified or deleted even after a new version is registered.
+
+/*  ============================================================
+    2. Domain
+    ============================================================ */
+
+sig Resource {}
+sig AnnualAssessment {}
+
+sig AssessmentTarget {
+ resource: one Resource,
+ year: one AnnualAssessment
+}
+
+sig AssessmentDataRevision {}
+sig ParameterSetRevision {}
+
+/*  ============================================================
+    3. State
+    ============================================================ */
+
+one sig Registry {
+ var assessmentData: AssessmentTarget -> lone AssessmentDataRevision,
+ var parameterSet: AssessmentTarget -> lone ParameterSetRevision
+}
+
+/*  ============================================================
+    4. Operations
+    ============================================================ */
+
+pred init {
+ no Registry.assessmentData
+ no Registry.parameterSet
+}
+
+pred registerAssessmentData[at: AssessmentTarget, adr: AssessmentDataRevision] {
+ Registry.assessmentData' = Registry.assessmentData + at -> adr
+ Registry.parameterSet' = Registry.parameterSet
+}
+
+pred registerParameterSet[at: AssessmentTarget, psr: ParameterSetRevision] {
+ Registry.assessmentData' = Registry.assessmentData
+ Registry.parameterSet' = Registry.parameterSet + at -> psr
+}
+
+pred stutter {
+ Registry.assessmentData' = Registry.assessmentData
+ Registry.parameterSet' = Registry.parameterSet
+}
+
+pred step {
+ stutter
+ or (some at: AssessmentTarget, adr: AssessmentDataRevision | registerAssessmentData[at, adr])
+ or (some at: AssessmentTarget, psr: ParameterSetRevision | registerParameterSet[at, psr])
+}
+
+fact traces {
+ init
+ always step
+}
+
+/*  ============================================================
+    5. Properties
+    ============================================================ */
+
+/*  ============================================================
+    6. Sanity
+    ============================================================ */
+
+run {} for 2 but 1..3 steps

runを実行してみると、下図のような関係が表示された:

システムの初期状態

（Alloyのおさらい）この図が意味していることは下記だ:

AssessmentTarger0 は AnnualAssessment と Resource1 からなる評価対象である
AssessmentTarger1 も同じ年の評価だが、対象資源は Resource0 である
Registry にはまだなにも登録されていない（= エッジが一本もない）
AssessmentDataRevision という概念がモデリングされているが使われていない（= データが登録されていない）

registerParameterSet predicateをstepに含めているにも関わらずデータが登録されていないことになっている理由は下記だ:

a. step内でregisterParameterSetの遷移がorの一つの選択肢として定義されているだけであり、その遷移が少なくとも一度選択されることは保証されていないため
- stutterが常に選択可能なら、すべてのステップでstutterだけが選択され、登録が一度も起きないトレースも許される
b. Alloyによるケース探索ではインスタンスから生成されがちだから²

逆に、データが登録された状況を見てみたければ下記のようにすれば良い:

  pred step {
-  stutter
-  or (some at: AssessmentTarget, adr: AssessmentDataRevision | registerAssessmentData[at, adr])
-  or (some at: AssessmentTarget, psr: ParameterSetRevision | registerParameterSet[at, psr])
+   some at: AssessmentTarget, adr: AssessmentDataRevision | registerAssessmentData[at, adr]
  }

↑力技でやるならこう。

こちらのほうがスマートか↓

- run {} for 2 but 1..3 steps
+ run { eventually (some Registry.assessmentData) } for 2 but 1..3 steps

実行すると、下図のようにデータが登録された状態を一応見ることができる:

データが登録されたケースの一例

図示のためのこの変更は不要だったので元に戻しておく。

ここから、各要件をAlloyで形式化し、全ての要件が常に満たされるシステム仕様となっているかを検証していく。「すべての要件が常に」と強めに書いたのは、各要件は私が定義した: つまり調整余地があるもなので、要件全体として整合するようにしたいからだ³。

SR001: 版による管理

SR001: 各評価データおよびパラメータセットは、版を用いて管理されなければならない

この要件は下記のように表現できる。

     5. Properties
     ============================================================ */
 
+assert SR001_revision_belongs_to_at_most_one_target {
+    all adr: AssessmentDataRevision |
+        lone Registry.assessmentData.adr
+
+    all psr: ParameterSetRevision |
+        lone Registry.parameterSet.psr
+}
+
+check SR001_revision_belongs_to_at_most_one_target for 2 but 1..3 steps
+
+pred SR001_revisions_can_be_registered {
+ eventually (some at: AssessmentTarget, adr: AssessmentDataRevision,
+  psr: ParameterSetRevision |
+  Registry.assessmentData[at] = adr
+  and Registry.parameterSet[at] = psr)
+}
+
+run SR001_revisions_can_be_registered for 2 but 1 AssessmentTarget, 1..3 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

Execute Allしてみる:

Executing "Check SR001_revision_belongs_to_at_most_one_target for 2 but 1..3 steps"
   Actual scopes: 2 Resource, 2 AnnualAssessment, 2 AssessmentTarget, 2 AssessmentDataRevision, 2 ParameterSetRevision, exactly 1 Registry
   Solver=sat4j Steps=1..3 Bitwidth=4 MaxSeq=2 SkolemDepth=1 Symmetry=20 Mode=batch
   1..3 steps. 1553 vars. 108 primary vars. 2564 clauses. 10ms.
   No counterexample found. Assertion may be valid. 0ms.

Executing "Run SR001_revisions_can_be_registered for 2 but 1..3 steps, 1 AssessmentTarget"
   Actual scopes: 2 Resource, 2 AnnualAssessment, 1 AssessmentTarget, 2 AssessmentDataRevision, 2 ParameterSetRevision, exactly 1 Registry
   Solver=sat4j Steps=1..3 Bitwidth=4 MaxSeq=2 SkolemDepth=1 Symmetry=20 Mode=batch
   1..3 steps. 2479 vars. 198 primary vars. 3967 clauses. 8ms.
   . found. Predicate is consistent. 3ms.

Executing "Run run$3 for 2 but 1..3 steps"
   Actual scopes: 2 Resource, 2 AnnualAssessment, 2 AssessmentTarget, 2 AssessmentDataRevision, 2 ParameterSetRevision, exactly 1 Registry
   Solver=sat4j Steps=1..3 Bitwidth=4 MaxSeq=2 SkolemDepth=1 Symmetry=20 Mode=batch
   1..1 steps. 2769 vars. 225 primary vars. 4415 clauses. 1ms.
   . found. Predicate is consistent. 2ms.

3 commands were executed. The results are:
   #1: No counterexample found. SR001_revision_belongs_to_at_most_one_target may be valid.
   #2: Instance found. SR001_revisions_can_be_registered is consistent.
   #3: Instance found. run$3 is consistent.

↑反例なし、全要件を満たすインスタンスあり（以下 OK ✅ と表現）。

SR002: 不変性

SR002: 登録後の版の内容を変更してはならない

これは下のように表現する:

  year: one AnnualAssessment
 }
 
-sig AssessmentDataRevision {}
-sig ParameterSetRevision {}
+sig AssessmentData {}
+sig ParameterSet {}
+
+sig RevisionId {}
+
+sig AssessmentDataRevision {
+    id: one RevisionId,
+    assessmentData: one AssessmentData
+}
+
+sig ParameterSetRevision {
+    id: one RevisionId,
+    parameterSet: one ParameterSet
+}
+
+fact revisionIdUnique {
+ all r1, r2: AssessmentDataRevision |
+  r1.id = r2.id implies r1 = r2
+ all r1, r2: ParameterSetRevision |
+  r1.id = r2.id implies r1 = r2
+}
 
 /*  ============================================================
     3. State
@@ -96,6 +115,28 @@ pred SR001_revisions_can_be_registered {
 
 run SR001_revisions_can_be_registered for 2 but 1 AssessmentTarget, 1..3 steps
 
+// SR002: The contents of a revision should not be modified after registration.
+// (Automatically satisfied by definition)
+
+pred SR002_registered_revision_contents_remain_available {
+ eventually (some at: AssessmentTarget,
+  adr: AssessmentDataRevision, psr: ParameterSetRevision,
+  data: AssessmentData, params: ParameterSet |
+  Registry.assessmentData[at] = adr
+  and adr.assessmentData = data
+  and Registry.parameterSet[at] = psr
+  and psr.parameterSet = params
+  and after (
+   Registry.assessmentData[at] = adr
+   and adr.assessmentData = data
+   and Registry.parameterSet[at] = psr
+   and psr.parameterSet = params
+  ))
+}
+
+run SR002_registered_revision_contents_remain_available
+ for 2 but 1 AssessmentTarget, 1..4 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

↑各Revisionに、非varのフィールドとして one AssessmentData と one ParameterSet を定義することによって保証する（保証といっても実装時の契約ではあるが）。

assertは追加していないが、この変更によって不整合が出ていないかをExecute Allで確認する:

4 commands were executed. The results are:
   #1: No counterexample found. SR001_revision_belongs_to_at_most_one_target may be valid.
   #2: Instance found. SR001_revisions_can_be_registered is consistent.
   #3: Instance found. SR002_registered_revision_contents_remain_available is consistent.
   #4: Instance found. run$4 is consistent.

OK ✅

こちらは全体のsanity check:

現時点のsanity checkを持たすモデル

↑AssessmentDataRevision と ParameterSetRevision が導入されたことで、モデルの構造が変わったのがわかる（スペース的に辛いのでノード数を減らしている）。

また、SR002の正常ケースの例をひとつ見てみたいので、明示的にegistered_revision_contents_remain_availableというrunも追加した:

SR002を満たすケースの一例

…いや待て。あるAssessmentDataRevisonと、あるParameterSetRevisionが同じRevisionIdを持ちうることになっているのか？それは意図と違う。

確かにちゃんとモデリングできていなかった:

 sig AssessmentData {}
 sig ParameterSet {}
 
-sig RevisionId {}
+abstract sig RevisionId {}
+sig AssessmentDataRevisionId, ParameterSetRevisionId extends RevisionId {}
 
 sig AssessmentDataRevision {
-    id: one RevisionId,
+    id: one AssessmentDataRevisionId,
     assessmentData: one AssessmentData
 }
 
 sig ParameterSetRevision {
-    id: one RevisionId,
+    id: one ParameterSetRevisionId,
     parameterSet: one ParameterSet
 }

もう一度状態を見てみる:

4 commands were executed. The results are:
   #1: No counterexample found. SR001_revision_belongs_to_at_most_one_target may be valid.
   #2: Instance found. SR001_revisions_can_be_registered is consistent.
   #3: Instance found. SR002_registered_cont_available is consistent.
   #4: Instance found. run$4 is consistent.

OK ✅

これで、AssessmentDataRevisonとParameterSetRevisionはそれぞれのRevisionIdを持つようになった。

SR002を満たすケースの一例（修正版）

Alloyの可視化機能に助けられた。

SR003: 不変性その2

SR003 : 評価データまたはパラメータセットを修正するときは、既存の版を更新せず、新しい版を作成しなければならない

 sig AssessmentDataRevisionId, ParameterSetRevisionId extends RevisionId {}
 
+// SR002: Each revision has unique identifier
 sig AssessmentDataRevision {
 id: one AssessmentDataRevisionId,
- assessmentData: one AssessmentData
+ assessmentData: one AssessmentData,
+ previousSource: lone AssessmentDataRevision
 }
 
 sig ParameterSetRevision {
  id: one ParameterSetRevisionId,
- parameterSet: one ParameterSet
+ parameterSet: one ParameterSet,
+ previousSource: lone ParameterSetRevision
 }
 
-fact revisionIdUnique {
- all r1, r2: AssessmentDataRevision |
-  r1.id = r2.id implies r1 = r2
- all r1, r2: ParameterSetRevision |
-  r1.id = r2.id implies r1 = r2
+// SR002: Unique identifier enforcement
+fact revisionIdUniqueAssessmentData {
+ all adr1, adr2: AssessmentDataRevision |
+  adr1.id = adr2.id implies adr1 = adr2
+}
+
+fact revisionIdUniqueParameterSet {
+ all psr1, psr2: ParameterSetRevision |
+  psr1.id = psr2.id implies psr1 = psr2
+}
+
+fact noCyclicSource {
+ all adr: AssessmentDataRevision | adr not in adr.^previousSource
+ all psr: ParameterSetRevision | psr not in psr.^previousSource
 }
 
 /*  ============================================================
@@ -54,8 +66,8 @@ fact revisionIdUnique {
     ============================================================ */
 
 one sig Registry {
- var assessmentData: AssessmentTarget -> lone AssessmentDataRevision,
- var parameterSet: AssessmentTarget -> lone ParameterSetRevision
+ var currentAssessmentData: AssessmentTarget -> lone AssessmentDataRevision,
+ var currentParameterSet: AssessmentTarget -> lone ParameterSetRevision
 }
 
 /*  ============================================================
@@ -63,23 +75,33 @@ one sig Registry {
     ============================================================ */
 
 pred init {
- no Registry.assessmentData
- no Registry.parameterSet
+ no Registry.currentAssessmentData
+ no Registry.currentParameterSet
 }
 
 pred registerAssessmentData[at: AssessmentTarget, adr: AssessmentDataRevision] {
- Registry.assessmentData' = Registry.assessmentData + at -> adr
- Registry.parameterSet' = Registry.parameterSet
+ (no Registry.currentAssessmentData[at] and no adr.previousSource)
+ or (
+  some Registry.currentAssessmentData[at]
+  and adr.previousSource = Registry.currentAssessmentData[at]
+ )
+ Registry.currentAssessmentData' = Registry.currentAssessmentData ++ at -> adr
+ Registry.currentParameterSet' = Registry.currentParameterSet
 }
 
 pred registerParameterSet[at: AssessmentTarget, psr: ParameterSetRevision] {
- Registry.assessmentData' = Registry.assessmentData
- Registry.parameterSet' = Registry.parameterSet + at -> psr
+ (no Registry.currentParameterSet[at] and no psr.previousSource)
+ or (
+  some Registry.currentParameterSet[at]
+  and psr.previousSource = Registry.currentParameterSet[at]
+ )
+ Registry.currentAssessmentData' = Registry.currentAssessmentData
+ Registry.currentParameterSet' = Registry.currentParameterSet ++ at -> psr
 }
 
 pred stutter {
- Registry.assessmentData' = Registry.assessmentData
- Registry.parameterSet' = Registry.parameterSet
+ Registry.currentAssessmentData' = Registry.currentAssessmentData
+ Registry.currentParameterSet' = Registry.currentParameterSet
 }
 
 pred step {
@@ -97,40 +119,32 @@ fact traces {
     5. Properties
     ============================================================ */
 
-assert SR001_revision_belongs_to_at_most_one_target {
-    all adr: AssessmentDataRevision |
-        lone Registry.assessmentData.adr
-
-    all psr: ParameterSetRevision |
-        lone Registry.parameterSet.psr
-}
-
-check SR001_revision_belongs_to_at_most_one_target for 2 but 1..3 steps
+// SR001: At most one current version per AssessmentTarget
+// (Automatically satisfied by Registry definition: lone AssessmentDataRevision)
 
 pred SR001_revisions_can_be_registered {
  eventually (some at: AssessmentTarget, adr: AssessmentDataRevision,
   psr: ParameterSetRevision |
-  Registry.assessmentData[at] = adr
-  and Registry.parameterSet[at] = psr)
+  Registry.currentAssessmentData[at] = adr
+  and Registry.currentParameterSet[at] = psr)
 }
 
 run SR001_revisions_can_be_registered for 2 but 1 AssessmentTarget, 1..3 steps
 
 // SR002: The contents of a revision should not be modified after registration.
 // (Automatically satisfied by definition)
-
 pred SR002_registered_cont_available {
  eventually (some at: AssessmentTarget,
   adr: AssessmentDataRevision, psr: ParameterSetRevision,
   data: AssessmentData, params: ParameterSet |
-  Registry.assessmentData[at] = adr
+  Registry.currentAssessmentData[at] = adr
   and adr.assessmentData = data
-  and Registry.parameterSet[at] = psr
+  and Registry.currentParameterSet[at] = psr
   and psr.parameterSet = params
   and after (
-   Registry.assessmentData[at] = adr
+   Registry.currentAssessmentData[at] = adr
    and adr.assessmentData = data
-   and Registry.parameterSet[at] = psr
+   and Registry.currentParameterSet[at] = psr
    and psr.parameterSet = params
   ))
 }
@@ -138,6 +152,46 @@ pred SR002_registered_cont_available {
 run SR002_registered_cont_available
  for 2 but 1 AssessmentTarget, 1..4 steps
 
+// SR003: When modifying, a new version must be created instead of updating the existing version
+assert SR003_new_version_on_change {
+ always (
+  (all at: AssessmentTarget |
+   (some Registry.currentAssessmentData[at] and some Registry.currentAssessmentData'[at])
+   implies Registry.currentAssessmentData[at] = Registry.currentAssessmentData'[at]
+    or Registry.currentAssessmentData'[at] in (Registry.currentAssessmentData[at]).~previousSource)
+  and
+  (all at: AssessmentTarget |
+   (some Registry.currentParameterSet[at] and some Registry.currentParameterSet'[at])
+   implies Registry.currentParameterSet[at] = Registry.currentParameterSet'[at]
+    or Registry.currentParameterSet'[at] in (Registry.currentParameterSet[at]).~previousSource)
+ )
+}
+
+check SR003_new_version_on_change for 2 but 1..3 steps
+
+pred SR003_assessment_data_can_be_changed_with_new_revision {
+ eventually (some at: AssessmentTarget,
+  source, newRevision: AssessmentDataRevision |
+  Registry.currentAssessmentData[at] = source
+  and source.assessmentData != newRevision.assessmentData
+  and newRevision.previousSource = source
+  and registerAssessmentData[at, newRevision])
+}
+
+pred SR003_parameter_set_can_be_changed_with_new_revision {
+ eventually (some at: AssessmentTarget,
+  source, newRevision: ParameterSetRevision |
+  Registry.currentParameterSet[at] = source
+  and source.parameterSet != newRevision.parameterSet
+  and newRevision.previousSource = source
+  and registerParameterSet[at, newRevision])
+}
+
+run SR003_assessment_data_can_be_changed_with_new_revision
+ for 2 but 1 AssessmentTarget, 1..3 steps
+run SR003_parameter_set_can_be_changed_with_new_revision
+ for 2 but 1 AssessmentTarget, 1..3 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

assert SR003_new_version_on_change の下記の部分は「current revisionが同じまま（変わらない）、または next revisionが current revision から派生している」を意味している:

implies Registry.currentAssessmentData[at] = Registry.currentAssessmentData'[at]
    or Registry.currentAssessmentData'[at] in (Registry.currentAssessmentData[at]).~previousSource)

Execute All:

6 commands were executed. The results are:
   #1: Instance found. SR001_revisions_can_be_registered is consistent.
   #2: Instance found. SR002_registered_cont_available is consistent.
   #3: No counterexample found. SR003_new_version_on_change may be valid.
   #4: Instance found. SR003_assessment_data_can_be_changed_with_new_revision is consistent.
   #5: Instance found. SR003_parameter_set_can_be_changed_with_new_revision is consistent.
   #6: Instance found. run$6 is consistent.

OK ✅

AssessmentDataが変わった際には、別のRevisionとなるようになっている:

SR003を満たすケースの一例

（末尾の数字が交差しているが、これは自動付与されたものなので気にしなくて良いはず。）

SR004: 版の参照規則

SR004: 新しい版は、既存の版を0個または1個参照しなければならない

これは、previousSource: lone AssessmentDataRevision の lone によって、既に定義レベルで保証されている。一応、状態を見てみたいのでrunを追加した:

  for 2 but 1 AssessmentTarget, 1..3 steps
 
+// SR004: Each revision can reference exactly zero or one previous version
+// (Enforced by previousSource: lone field definition - no explicit assertion needed)
+
+pred SR004_root_and_derived_revisions_can_exist {
+ some rootAdr, derivedAdr: AssessmentDataRevision,
+  rootPsr, derivedPsr: ParameterSetRevision |
+  rootAdr != derivedAdr
+  and no rootAdr.previousSource
+  and derivedAdr.previousSource = rootAdr
+  and rootPsr != derivedPsr
+  and no rootPsr.previousSource
+  and derivedPsr.previousSource = rootPsr
+}
+
+run SR004_root_and_derived_revisions_can_exist
+ for 4 but
+ exactly 2 AssessmentDataRevision,
+ exactly 2 ParameterSetRevision,
+ exactly 2 AssessmentDataRevisionId,
+ exactly 2 ParameterSetRevisionId,
+ 1..2 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

一例を見てみる:

SR004を満たすケースの一例

なるほど、データの内容が同じでも親が違う状況が示されていて、この場合には違う版として扱われるらしい。少し意図と違うが、これについては次のSR005で考える。

SR005: 冪等性

SR005: 同一の登録要求識別子を持つ登録要求に対しては同一の結果を返し、新たな版を重複して作成してはならない

先ほど述べた問題にも関係する冪等性。下記のようにモデリングしてみる:

 sig AssessmentDataRevisionId, ParameterSetRevisionId extends RevisionId {}
 
+sig HashKey {}
+
+abstract sig Status {}
+one sig Success, Failure extends Status {}
+
+sig Response {
+ revision: lone (AssessmentDataRevision + ParameterSetRevision),
+ status: one Status
+}
+
 // SR002: Each revision has unique identifier
 sig AssessmentDataRevision {
  id: one AssessmentDataRevisionId,
@@ -67,7 +77,9 @@ fact noCyclicSource {
 
 one sig Registry {
  var currentAssessmentData: AssessmentTarget -> lone AssessmentDataRevision,
- var currentParameterSet: AssessmentTarget -> lone ParameterSetRevision
+ var currentParameterSet: AssessmentTarget -> lone ParameterSetRevision,
+ // SR005: Track responses by HashKey (idempotency key) for idempotency verification
+ var responseLog: HashKey -> lone Response
 }
 
 /*  ============================================================
@@ -77,37 +89,80 @@ one sig Registry {
 pred init {
  no Registry.currentAssessmentData
  no Registry.currentParameterSet
+ no Registry.responseLog
 }
 
-pred registerAssessmentData[at: AssessmentTarget, adr: AssessmentDataRevision] {
- (no Registry.currentAssessmentData[at] and no adr.previousSource)
+// SR005: Log response by idempotency key
+pred registerAssessmentData[
+ at: AssessmentTarget,
+ adr: AssessmentDataRevision,
+ data: AssessmentData,
+ idempotencyKey: HashKey
+] {
+  adr.assessmentData = data
+  and
+ (
+  no Registry.responseLog[idempotencyKey]
+  and (
+   (no Registry.currentAssessmentData[at] and no adr.previousSource)
+   or (
+    some Registry.currentAssessmentData[at]
+    and adr.previousSource = Registry.currentAssessmentData[at]
+   )
+  )
+  and Registry.currentAssessmentData' = Registry.currentAssessmentData ++ at -> adr
+  and Registry.currentParameterSet' = Registry.currentParameterSet
+  and some r: Response |
+   r.revision = adr
+   and r.status = Success
+   and Registry.responseLog' = Registry.responseLog + idempotencyKey -> r
+ )
  or (
-  some Registry.currentAssessmentData[at]
-  and adr.previousSource = Registry.currentAssessmentData[at]
+  some Registry.responseLog[idempotencyKey]
+  and Registry.currentAssessmentData' = Registry.currentAssessmentData
+  and Registry.currentParameterSet' = Registry.currentParameterSet
+  and Registry.responseLog' = Registry.responseLog
  )
- Registry.currentAssessmentData' = Registry.currentAssessmentData ++ at -> adr
- Registry.currentParameterSet' = Registry.currentParameterSet
 }
 
-pred registerParameterSet[at: AssessmentTarget, psr: ParameterSetRevision] {
- (no Registry.currentParameterSet[at] and no psr.previousSource)
+pred registerParameterSet[
+ at: AssessmentTarget,
+ psr: ParameterSetRevision,
+ params: ParameterSet,
+ idempotencyKey: HashKey
+] {
+  psr.parameterSet = params
+  and
+ (
+  no Registry.responseLog[idempotencyKey]
+  and (
+   (no Registry.currentParameterSet[at] and no psr.previousSource)
+   or (
+    some Registry.currentParameterSet[at]
+    and psr.previousSource = Registry.currentParameterSet[at]
+   )
+  )
+  and Registry.currentAssessmentData' = Registry.currentAssessmentData
+  and Registry.currentParameterSet' = Registry.currentParameterSet ++ at -> psr
+  and some r: Response |
+   r.revision = psr
+   and r.status = Success
+   and Registry.responseLog' = Registry.responseLog + idempotencyKey -> r
+ )
  or (
-  some Registry.currentParameterSet[at]
-  and psr.previousSource = Registry.currentParameterSet[at]
+  some Registry.responseLog[idempotencyKey]
+  and Registry.currentAssessmentData' = Registry.currentAssessmentData
+  and Registry.currentParameterSet' = Registry.currentParameterSet
+  and Registry.responseLog' = Registry.responseLog
  )
- Registry.currentAssessmentData' = Registry.currentAssessmentData
- Registry.currentParameterSet' = Registry.currentParameterSet ++ at -> psr
 }
 
 pred stutter {
  Registry.currentAssessmentData' = Registry.currentAssessmentData
  Registry.currentParameterSet' = Registry.currentParameterSet
+ Registry.responseLog' = Registry.responseLog
 }
 
 pred step {
  stutter
- or (some at: AssessmentTarget, adr: AssessmentDataRevision | registerAssessmentData[at, adr])
- or (some at: AssessmentTarget, psr: ParameterSetRevision | registerParameterSet[at, psr])
+ or (some at: AssessmentTarget, adr: AssessmentDataRevision, data: AssessmentData, hk: HashKey |
+  registerAssessmentData[at, adr, data, hk])
+ or (some at: AssessmentTarget, psr: ParameterSetRevision, params: ParameterSet, hk: HashKey |
+  registerParameterSet[at, psr, params, hk])
 }
 
 fact traces {
@@ -171,20 +226,22 @@ check SR003_new_version_on_change for 2 but 1..3 steps
 
 pred SR003_assessment_update {
  eventually (some at: AssessmentTarget,
-  source, newRevision: AssessmentDataRevision |
+  source, newRevision: AssessmentDataRevision,
+  data: AssessmentData, hk: HashKey |
   Registry.currentAssessmentData[at] = source
-  and source.assessmentData != newRevision.assessmentData
+  and source.assessmentData != data
   and newRevision.previousSource = source
-  and registerAssessmentData[at, newRevision])
+  and registerAssessmentData[at, newRevision, data, hk])
 }
 
 pred SR003_parameter_update {
  eventually (some at: AssessmentTarget,
-  source, newRevision: ParameterSetRevision |
+  source, newRevision: ParameterSetRevision,
+  params: ParameterSet, hk: HashKey |
   Registry.currentParameterSet[at] = source
-  and source.parameterSet != newRevision.parameterSet
+  and source.parameterSet != params
   and newRevision.previousSource = source
-  and registerParameterSet[at, newRevision])
+  and registerParameterSet[at, newRevision, params, hk])
 }
 
 run SR003_assessment_update
@@ -214,6 +271,51 @@ run SR004_revision_chain
  exactly 2 ParameterSetRevisionId,
  1..2 steps
 
+// SR005: Idempotency - same HashKey (idempotency key) returns same response
+assert SR005_idempotency {
+ always (
+  all hk: HashKey |
+   (some Registry.responseLog[hk]) implies always Registry.responseLog[hk] = Registry.responseLog'[hk]
+ )
+}
+
+check SR005_idempotency for 2 but 1..3 steps
+
+pred SR005_assessment_data_retry_returns_same_response {
+ some at: AssessmentTarget, adr: AssessmentDataRevision,
+  data: AssessmentData, hk: HashKey, r: Response |
+  eventually (
+   no Registry.responseLog[hk]
+   and registerAssessmentData[at, adr, data, hk]
+   and Registry.responseLog'[hk] = r
+   and after (
+    Registry.responseLog[hk] = r
+    and registerAssessmentData[at, adr, data, hk]
+    and Registry.responseLog'[hk] = r
+   )
+  )
+}
+
+pred SR005_parameter_set_retry_returns_same_response {
+ some at: AssessmentTarget, psr: ParameterSetRevision,
+  params: ParameterSet, hk: HashKey, r: Response |
+  eventually (
+   no Registry.responseLog[hk]
+   and registerParameterSet[at, psr, params, hk]
+   and Registry.responseLog'[hk] = r
+   and after (
+    Registry.responseLog[hk] = r
+    and registerParameterSet[at, psr, params, hk]
+    and Registry.responseLog'[hk] = r
+   )
+  )
+}
+
+run SR005_assessment_data_retry_returns_same_response
+ for 2 but 1 AssessmentTarget, 1..3 steps
+run SR005_parameter_set_retry_returns_same_response
+ for 2 but 1 AssessmentTarget, 1..3 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

var responseLog: HashKey -> lone Response の右辺がoneではなくloneなのは、データが未登録の状況を表現するため。実装時における冪等性保証を助けるために、リクエストにはidempotency keyを使う想定。このkeyの計算には、親とする版のIDも含める必要がある。始めはAssessmentDataなどの内容のみからkeyを生成して、同一の内容の登録リクエストは拒否してしまおうと考えていたが、そうすると履歴の復元: 内容が同じデータの再登録の時に不都合が出そう。

ともあれ、同一性の定義については詳細設計に回すとして、ひとまず次に進む。

Execute All:

10 commands were executed. The results are:
   #1: Instance found. SR001_registration is consistent.
   #2: Instance found. SR002_content_stability is consistent.
   #3: No counterexample found. SR003_new_version_on_change may be valid.
   #4: Instance found. SR003_assessment_update is consistent.
   #5: Instance found. SR003_parameter_update is consistent.
   #6: Instance found. SR004_revision_chain is consistent.
   #7: No counterexample found. SR005_idempotency may be valid.
   #8: Instance found. SR005_assessment_retry is consistent.
   #9: Instance found. SR005_parameter_retry is consistent.
   #10: Instance found. run$10 is consistent.

↑OK :white_check_mark

SR005を満たすケースの一例

↑同一のHashKeyとともに何度リクエストしても、Revisionは変化しない様子が示されている。

SR006: 取得可能性

SR006: 登録処理が成功した場合、取得APIから登録された版の内容を取得できなければならない

この要件は「成功レスポンスがあるならRevisionが存在する」として表現する:

 one sig Registry {
  var currentAssessmentData: AssessmentTarget -> lone AssessmentDataRevision,
  var currentParameterSet: AssessmentTarget -> lone ParameterSetRevision,
+ var registeredAssessmentData: AssessmentTarget -> set AssessmentDataRevision,
+ var registeredParameterSet: AssessmentTarget -> set ParameterSetRevision,
  // SR005: Track responses by HashKey (idempotency key) for idempotency verification
  var responseLog: HashKey -> lone Response
 }
@@ -89,6 +91,8 @@ one sig Registry {
 pred init {
  no Registry.currentAssessmentData
  no Registry.currentParameterSet
+ no Registry.registeredAssessmentData
+ no Registry.registeredParameterSet
  no Registry.responseLog
 }
 
@@ -109,6 +113,8 @@ pred registerAssessmentData[
   )
   and Registry.currentAssessmentData' = Registry.currentAssessmentData ++ at -> adr
   and Registry.currentParameterSet' = Registry.currentParameterSet
+  and Registry.registeredAssessmentData' = Registry.registeredAssessmentData + at -> adr
+  and Registry.registeredParameterSet' = Registry.registeredParameterSet
   and some r: Response |
    r.revision = adr
    and r.status = Success
@@ -118,6 +124,8 @@ pred registerAssessmentData[
   some Registry.responseLog[idempotencyKey]
   and Registry.currentAssessmentData' = Registry.currentAssessmentData
   and Registry.currentParameterSet' = Registry.currentParameterSet
+  and Registry.registeredAssessmentData' = Registry.registeredAssessmentData
+  and Registry.registeredParameterSet' = Registry.registeredParameterSet
   and Registry.responseLog' = Registry.responseLog
  )
 }
@@ -138,6 +146,8 @@ pred registerParameterSet[
   )
   and Registry.currentAssessmentData' = Registry.currentAssessmentData
   and Registry.currentParameterSet' = Registry.currentParameterSet ++ at -> psr
+  and Registry.registeredAssessmentData' = Registry.registeredAssessmentData
+  and Registry.registeredParameterSet' = Registry.registeredParameterSet + at -> psr
   and some r: Response |
    r.revision = psr
    and r.status = Success
@@ -147,6 +157,8 @@ pred registerParameterSet[
   some Registry.responseLog[idempotencyKey]
   and Registry.currentAssessmentData' = Registry.currentAssessmentData
   and Registry.currentParameterSet' = Registry.currentParameterSet
+  and Registry.registeredAssessmentData' = Registry.registeredAssessmentData
+  and Registry.registeredParameterSet' = Registry.registeredParameterSet
   and Registry.responseLog' = Registry.responseLog
  )
 }
@@ -154,6 +166,8 @@ pred registerParameterSet[
 pred stutter {
  Registry.currentAssessmentData' = Registry.currentAssessmentData
  Registry.currentParameterSet' = Registry.currentParameterSet
+ Registry.registeredAssessmentData' = Registry.registeredAssessmentData
+ Registry.registeredParameterSet' = Registry.registeredParameterSet
  Registry.responseLog' = Registry.responseLog
 }
 
@@ -316,6 +330,47 @@ run SR005_assessment_retry
 run SR005_parameter_retry
  for 2 but 1 AssessmentTarget, 1..3 steps
 
+// SR006: After successful registration, the registered version must be retrievable
+// If response is logged as successful, the revision must remain registered
+assert SR006_retrievability {
+ always (
+  all hk: HashKey, r: Response |
+   (some Registry.responseLog[hk] and Registry.responseLog[hk] = r and r.status = Success)
+   implies (
+    (some at: AssessmentTarget, adr: AssessmentDataRevision |
+     r.revision = adr and adr in Registry.registeredAssessmentData[at])
+    or
+    (some at: AssessmentTarget, psr: ParameterSetRevision |
+     r.revision = psr and psr in Registry.registeredParameterSet[at])
+   )
+ )
+}
+
+check SR006_retrievability for 2 but 1..3 steps
+
+pred SR006_registered_assessment_data_can_be_retrieved {
+ eventually (some at: AssessmentTarget, adr: AssessmentDataRevision,
+  hk: HashKey, r: Response |
+  Registry.responseLog[hk] = r
+  and r.status = Success
+  and r.revision = adr
+  and adr in Registry.registeredAssessmentData[at])
+}
+
+pred SR006_registered_parameter_set_can_be_retrieved {
+ eventually (some at: AssessmentTarget, psr: ParameterSetRevision,
+  hk: HashKey, r: Response |
+  Registry.responseLog[hk] = r
+  and r.status = Success
+  and r.revision = psr
+  and psr in Registry.registeredParameterSet[at])
+}
+
+run SR006_registered_assessment_data_can_be_retrieved
+ for 2 but 1 AssessmentTarget, 1..3 steps
+run SR006_registered_parameter_set_can_be_retrieved
+ for 2 but 1 AssessmentTarget, 1..3 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

Execute All:

13 commands were executed. The results are:
   #1: Instance found. SR001_registration is consistent.
   #2: Instance found. SR002_content_stability is consistent.
   #3: No counterexample found. SR003_new_version_on_change may be valid.
   #4: Instance found. SR003_assessment_update is consistent.
   #5: Instance found. SR003_parameter_update is consistent.
   #6: Instance found. SR004_revision_chain is consistent.
   #7: No counterexample found. SR005_idempotency may be valid.
   #8: Instance found. SR005_assessment_retry is consistent.
   #9: Instance found. SR005_parameter_retry is consistent.
   #10: No counterexample found. SR006_retrievability may be valid.
   #11: Instance found. SR006_assessment_retrieval is consistent.
   #12: Instance found. SR006_parameter_retrieval is consistent.
   #13: Instance found. run$13 is consistent.

↑OK ✅

SR006の例示結果はSR005と変わらなかった。

SR007: 取得可能性その2

R007: 版を指定した取得要求には、その版に記録された内容を返さなければならない

これは原理的にはSR001とSR002で既に満たされている:

 run SR006_parameter_retrieval
  for 2 but 1 AssessmentTarget, 1..3 steps
 
+// SR007: Retrieval requests return the contents recorded in that version
+// (Automatically satisfied because revision content is immutable)
+
+pred SR007_assessment_data_can_be_retrieved_by_revision {
+ eventually (some at: AssessmentTarget, adr: AssessmentDataRevision,
+  data: AssessmentData |
+  adr in Registry.registeredAssessmentData[at]
+  and data = adr.assessmentData)
+}
+
+pred SR007_parameter_set_can_be_retrieved_by_revision {
+ eventually (some at: AssessmentTarget, psr: ParameterSetRevision,
+  params: ParameterSet |
+  psr in Registry.registeredParameterSet[at]
+  and params = psr.parameterSet)
+}
+
+run SR007_assessment_data_can_be_retrieved_by_revision
+ for 2 but 1 AssessmentTarget, 1..3 steps
+run SR007_parameter_set_can_be_retrieved_by_revision
+ for 2 but 1 AssessmentTarget, 1..3 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

実際の挙動がこれを満たすようにするのは実装時の責任。

15 commands were executed. The results are:
   #1: Instance found. SR001_registration is consistent.
   #2: Instance found. SR002_content_stability is consistent.
   #3: No counterexample found. SR003_new_version_on_change may be valid.
   #4: Instance found. SR003_assessment_update is consistent.
   #5: Instance found. SR003_parameter_update is consistent.
   #6: Instance found. SR004_revision_chain is consistent.
   #7: No counterexample found. SR005_idempotency may be valid.
   #8: Instance found. SR005_assessment_retry is consistent.
   #9: Instance found. SR005_parameter_retry is consistent.
   #10: No counterexample found. SR006_retrievability may be valid.
   #11: Instance found. SR006_assessment_retrieval is consistent.
   #12: Instance found. SR006_parameter_retrieval is consistent.
   #13: Instance found. SR007_assessment_by_revision is consistent.
   #14: Instance found. SR007_parameter_by_revision is consistent.
   #15: Instance found. run$15 is consistent.

↑OK ✅

今回の変更も、モデルに構造的な変化はなかった。

SR008: 最新版の参照

SR008 評価データおよびパラメータセットは、それぞれ高々1つの最新版を持たなければならない

この要件は、既にRegistryの設計レベルで保証されている。保証しているのは、下記current-のlone参照だ:

one sig Registry {
  one sig Registry {
 var currentAssessmentData: AssessmentTarget -> lone AssessmentDataRevision,
 var currentParameterSet: AssessmentTarget -> lone ParameterSetRevision,
 var registeredAssessmentData: AssessmentTarget -> set AssessmentDataRevision,
 var registeredParameterSet: AssessmentTarget -> set ParameterSetRevision,
 // SR005: Track responses by HashKey (idempotency key) for idempotency verification
 var responseLog: HashKey -> lone Response
}

一応、ここでも正常ケースを例示しておく:

 run SR007_parameter_by_revision
  for 2 but 1 AssessmentTarget, 1..3 steps
 
+// SR008: AssessmentData and ParameterSet each have at most one current revision
+// (Enforced by the lone multiplicity of the current revision fields)
+
+pred SR008_assessment_data_has_one_current_among_registered_revisions {
+ eventually (some at: AssessmentTarget,
+  disj previousRevision, currentRevision: AssessmentDataRevision |
+  previousRevision + currentRevision in Registry.registeredAssessmentData[at]
+  and Registry.currentAssessmentData[at] = currentRevision)
+}
+
+pred SR008_parameter_set_has_one_current_among_registered_revisions {
+ eventually (some at: AssessmentTarget,
+  disj previousRevision, currentRevision: ParameterSetRevision |
+  previousRevision + currentRevision in Registry.registeredParameterSet[at]
+  and Registry.currentParameterSet[at] = currentRevision)
+}
+
+run SR008_assessment_data_has_one_current_among_registered_revisions
+ for 3 but 1 AssessmentTarget, 1..3 steps
+run SR008_parameter_set_has_one_current_among_registered_revisions
+ for 3 but 1 AssessmentTarget, 1..3 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

Execute All:

17 commands were executed. The results are:
   #1: Instance found. SR001_registration is consistent.
   #2: Instance found. SR002_content_stability is consistent.
   #3: No counterexample found. SR003_new_version_on_change may be valid.
   #4: Instance found. SR003_assessment_update is consistent.
   #5: Instance found. SR003_parameter_update is consistent.
   #6: Instance found. SR004_revision_chain is consistent.
   #7: No counterexample found. SR005_idempotency may be valid.
   #8: Instance found. SR005_assessment_retry is consistent.
   #9: Instance found. SR005_parameter_retry is consistent.
   #10: No counterexample found. SR006_retrievability may be valid.
   #11: Instance found. SR006_assessment_retrieval is consistent.
   #12: Instance found. SR006_parameter_retrieval is consistent.
   #13: Instance found. SR007_assessment_by_revision is consistent.
   #14: Instance found. SR007_parameter_by_revision is consistent.
   #15: Instance found. SR008_assessment_current is consistent.
   #16: Instance found. SR008_parameter_current is consistent.
   #17: Instance found. run$17 is consistent.

↑ OK ✅

正常系を図示する:

SR008を満たすケースの一例

↑この例では、RegistryはAssessmentDataRevision0を最新版として参照している。

SR009: 登録成功後の最新版の参照

SR009: 新しい版の登録成功後、最新版は新しい版を指さなければならない

この要件は、registerAssessmentData などのpredの定義で保証済み。具体的には下記の部分だ:

pred registerAssessmentData[at: AssessmentTarget, assessmentData: AssessmentData, idempotencyKey: HashKey] {
 some adr: AssessmentDataRevision |
  idempotencyKey = adr.id and
  adr.assessmentData = assessmentData and
  Registry.currentAssessmentData' = Registry.currentAssessmentData + at -> adr and
  Registry.currentParameterSet' = Registry.currentParameterSet and
  some r: Response |
   r.revision = adr and
   r.status = Success and
   Registry.responseLog' = Registry.responseLog + idempotencyKey -> r
}

この定義は、例えば下記のような状況を表現している:

AssessmentTargetが2026年度カタクチ太平洋、currentAssessmentDataがsomeRevisionHashに紐づくデータである状態
新しい登録リクエストが届く: 「2026年度カタクチ太平洋、新しいassessmentData、新しいidempotency key」
newRevisionHashと紐づいたcurrentAssessmentDataが2026年度のカタクチ太平洋の最新版として保持される

ここでも正常系を明示的に例示してみる:

 run SR008_parameter_current
  for 3 but 1 AssessmentTarget, 1..3 steps
 
+// SR009: Successful registration makes the new revision current
+
+pred SR009_assessment_advance {
+ eventually (some at: AssessmentTarget,
+  disj previousRevision, newRevision: AssessmentDataRevision,
+  data: AssessmentData, hk: HashKey |
+  Registry.currentAssessmentData[at] = previousRevision
+  and newRevision.previousSource = previousRevision
+  and no Registry.responseLog[hk]
+  and registerAssessmentData[at, newRevision, data, hk]
+  and Registry.currentAssessmentData'[at] = newRevision)
+}
+
+pred SR009_parameter_advance {
+ eventually (some at: AssessmentTarget,
+  disj previousRevision, newRevision: ParameterSetRevision,
+  params: ParameterSet, hk: HashKey |
+  Registry.currentParameterSet[at] = previousRevision
+  and newRevision.previousSource = previousRevision
+  and no Registry.responseLog[hk]
+  and registerParameterSet[at, newRevision, params, hk]
+  and Registry.currentParameterSet'[at] = newRevision)
+}
+
+run SR009_assessment_advance
+ for 3 but 1 AssessmentTarget, 1..3 steps
+run SR009_parameter_advance
+ for 3 but 1 AssessmentTarget, 1..3 steps
+
 /*  ============================================================
     6. Sanity
     ============================================================ */

Execute Allはall green ✅

SR009を満たすケースの一例

こちらも、モデルに構造的な変化は見られないように思う。

SR010: 不変性その3

SR010: 新しい版が登録されても、過去の版を変更または削除してはならない

こちらは実装の責任なのでモデル検証はスキップ。

モデル全体

ここまでの検証で、Alloyのコード全体は最終的に下記のようになった:

module DataRegistry

/*  ============================================================
    1. System Requirements
    ============================================================ */
// SR001: Each AssessmentData and ParameterSet should be managed through revisions.
// SR002: The contents of a revision should not be modified after registration.
// SR003: When modifying AssessmentData or ParameterSet, a new version must be created instead of updating the existing version.
// SR004: A new version must reference exactly zero or one previous version as its source.
// SR005: For registration requests with identical IdempotencyKey, the same result must be returned without creating duplicate versions.
// SR006: After successful registration, the registered version must be retrievable via the retrieval API.
// SR007: Retrieval requests specifying a version must return the contents recorded in that version.
// SR008: AssessmentData and ParameterSet must each have at most one current version.
// SR009: After successful registration of a new version, the current version must point to the new version.
// SR010: Past versions must not be modified or deleted even after a new version is registered.

/*  ============================================================
    2. Domain
    ============================================================ */

sig Resource {}
sig AnnualAssessment {}

sig AssessmentTarget {
 resource: one Resource,
    year: one AnnualAssessment
}

sig AssessmentData {}
sig ParameterSet {}

abstract sig RevisionId {}
sig AssessmentDataRevisionId, ParameterSetRevisionId extends RevisionId {}

sig HashKey {}

abstract sig Status {}
one sig Success, Failure extends Status {}

sig Response {
 revision: lone (AssessmentDataRevision + ParameterSetRevision),
 status: one Status
}

// SR002: Each revision has unique identifier
sig AssessmentDataRevision {
 id: one AssessmentDataRevisionId,
 assessmentData: one AssessmentData,
 previousSource: lone AssessmentDataRevision
}

sig ParameterSetRevision {
 id: one ParameterSetRevisionId,
 parameterSet: one ParameterSet,
 previousSource: lone ParameterSetRevision
}

// SR002: Unique identifier enforcement
fact revisionIdUniqueAssessmentData {
 all adr1, adr2: AssessmentDataRevision |
  adr1.id = adr2.id implies adr1 = adr2
}

fact revisionIdUniqueParameterSet {
 all psr1, psr2: ParameterSetRevision |
  psr1.id = psr2.id implies psr1 = psr2
}

fact noCyclicSource {
 all adr: AssessmentDataRevision | adr not in adr.^previousSource
 all psr: ParameterSetRevision | psr not in psr.^previousSource
}

/*  ============================================================
    3. State
    ============================================================ */

one sig Registry {
 var currentAssessmentData: AssessmentTarget -> lone AssessmentDataRevision,
 var currentParameterSet: AssessmentTarget -> lone ParameterSetRevision,
 var registeredAssessmentData: AssessmentTarget -> set AssessmentDataRevision,
 var registeredParameterSet: AssessmentTarget -> set ParameterSetRevision,
 // SR005: Track responses by HashKey (idempotency key) for idempotency verification
 var responseLog: HashKey -> lone Response
}

/*  ============================================================
    4. Operations
    ============================================================ */

pred init {
 no Registry.currentAssessmentData
 no Registry.currentParameterSet
 no Registry.registeredAssessmentData
 no Registry.registeredParameterSet
 no Registry.responseLog
}

// SR005: Log response by idempotency key
pred registerAssessmentData[
 at: AssessmentTarget,
 adr: AssessmentDataRevision,
 idempotencyKey: HashKey
] {
 (
  no Registry.responseLog[idempotencyKey]
  and (
 (no Registry.currentAssessmentData[at] and no adr.previousSource)
 or (
  some Registry.currentAssessmentData[at]
  and adr.previousSource = Registry.currentAssessmentData[at]
 )
  )
  and Registry.currentAssessmentData' = Registry.currentAssessmentData ++ at -> adr
  and Registry.currentParameterSet' = Registry.currentParameterSet
  and Registry.registeredAssessmentData' = Registry.registeredAssessmentData + at -> adr
  and Registry.registeredParameterSet' = Registry.registeredParameterSet
  and some r: Response |
   r.revision = adr
   and r.status = Success
   and Registry.responseLog' = Registry.responseLog + idempotencyKey -> r
 )
 or (
  some Registry.responseLog[idempotencyKey]
  and Registry.currentAssessmentData' = Registry.currentAssessmentData
  and Registry.currentParameterSet' = Registry.currentParameterSet
  and Registry.registeredAssessmentData' = Registry.registeredAssessmentData
  and Registry.registeredParameterSet' = Registry.registeredParameterSet
  and Registry.responseLog' = Registry.responseLog
 )
}

pred registerParameterSet[
 at: AssessmentTarget,
 psr: ParameterSetRevision,
 idempotencyKey: HashKey
] {
 (
  no Registry.responseLog[idempotencyKey]
  and (
 (no Registry.currentParameterSet[at] and no psr.previousSource)
 or (
  some Registry.currentParameterSet[at]
  and psr.previousSource = Registry.currentParameterSet[at]
 )
  )
  and Registry.currentAssessmentData' = Registry.currentAssessmentData
  and Registry.currentParameterSet' = Registry.currentParameterSet ++ at -> psr
  and Registry.registeredAssessmentData' = Registry.registeredAssessmentData
  and Registry.registeredParameterSet' = Registry.registeredParameterSet + at -> psr
  and some r: Response |
   r.revision = psr
   and r.status = Success
   and Registry.responseLog' = Registry.responseLog + idempotencyKey -> r
 )
 or (
  some Registry.responseLog[idempotencyKey]
  and Registry.currentAssessmentData' = Registry.currentAssessmentData
  and Registry.currentParameterSet' = Registry.currentParameterSet
  and Registry.registeredAssessmentData' = Registry.registeredAssessmentData
  and Registry.registeredParameterSet' = Registry.registeredParameterSet
  and Registry.responseLog' = Registry.responseLog
 )
}

pred stutter {
 Registry.currentAssessmentData' = Registry.currentAssessmentData
 Registry.currentParameterSet' = Registry.currentParameterSet
 Registry.registeredAssessmentData' = Registry.registeredAssessmentData
 Registry.registeredParameterSet' = Registry.registeredParameterSet
 Registry.responseLog' = Registry.responseLog
}

pred step {
 stutter
 or (some at: AssessmentTarget, adr: AssessmentDataRevision, hk: HashKey |
  registerAssessmentData[at, adr, hk])
 or (some at: AssessmentTarget, psr: ParameterSetRevision, hk: HashKey |
  registerParameterSet[at, psr, hk])
}

fact traces {
 init
 always step
}

/*  ============================================================
    5. Properties
    ============================================================ */

// SR001: At most one current version per AssessmentTarget
// (Automatically satisfied by Registry definition: lone AssessmentDataRevision)

pred SR001_registration {
 eventually (some at: AssessmentTarget, adr: AssessmentDataRevision,
  psr: ParameterSetRevision |
  Registry.currentAssessmentData[at] = adr
  and Registry.currentParameterSet[at] = psr)
}

run SR001_registration for 2 but 1 AssessmentTarget, 1..3 steps

// SR002: The contents of a revision should not be modified after registration.
// (Automatically satisfied by definition)
pred SR002_content_stability {
 eventually (some at: AssessmentTarget,
  adr: AssessmentDataRevision, psr: ParameterSetRevision,
  data: AssessmentData, params: ParameterSet |
  Registry.currentAssessmentData[at] = adr
  and adr.assessmentData = data
  and Registry.currentParameterSet[at] = psr
  and psr.parameterSet = params
  and after (
   Registry.currentAssessmentData[at] = adr
   and adr.assessmentData = data
   and Registry.currentParameterSet[at] = psr
   and psr.parameterSet = params
  ))
}

run SR002_content_stability
 for 2 but 1 AssessmentTarget, 1..4 steps

// SR003: When modifying, a new version must be created instead of updating the existing version
assert SR003_new_version_on_change {
 always (
  (all at: AssessmentTarget |
   (some Registry.currentAssessmentData[at] and some Registry.currentAssessmentData'[at])
   implies Registry.currentAssessmentData[at] = Registry.currentAssessmentData'[at]
    or Registry.currentAssessmentData'[at] in (Registry.currentAssessmentData[at]).~previousSource)
  and
  (all at: AssessmentTarget |
   (some Registry.currentParameterSet[at] and some Registry.currentParameterSet'[at])
   implies Registry.currentParameterSet[at] = Registry.currentParameterSet'[at]
    or Registry.currentParameterSet'[at] in (Registry.currentParameterSet[at]).~previousSource)
 )
}

check SR003_new_version_on_change for 2 but 1..3 steps

pred SR003_assessment_update {
 eventually (some at: AssessmentTarget,
  source, newRevision: AssessmentDataRevision,
  hk: HashKey |
  Registry.currentAssessmentData[at] = source
  and source.assessmentData != newRevision.assessmentData
  and newRevision.previousSource = source
  and registerAssessmentData[at, newRevision, hk])
}

pred SR003_parameter_update {
 eventually (some at: AssessmentTarget,
  source, newRevision: ParameterSetRevision,
  hk: HashKey |
  Registry.currentParameterSet[at] = source
  and source.parameterSet != newRevision.parameterSet
  and newRevision.previousSource = source
  and registerParameterSet[at, newRevision, hk])
}

run SR003_assessment_update
 for 2 but 1 AssessmentTarget, 1..3 steps
run SR003_parameter_update
 for 2 but 1 AssessmentTarget, 1..3 steps

// SR004: Each revision can reference exactly zero or one previous version
// (Enforced by previousSource: lone field definition - no explicit assertion needed)

pred SR004_revision_chain {
 some rootAdr, derivedAdr: AssessmentDataRevision,
  rootPsr, derivedPsr: ParameterSetRevision |
  rootAdr != derivedAdr
  and no rootAdr.previousSource
  and derivedAdr.previousSource = rootAdr
  and rootPsr != derivedPsr
  and no rootPsr.previousSource
  and derivedPsr.previousSource = rootPsr
}

run SR004_revision_chain
 for 4 but
 exactly 2 AssessmentDataRevision,
 exactly 2 ParameterSetRevision,
 exactly 2 AssessmentDataRevisionId,
 exactly 2 ParameterSetRevisionId,
 1..2 steps

// SR005: Idempotency - same HashKey (idempotency key) returns same response
assert SR005_idempotency {
 always (
  all hk: HashKey |
   (some Registry.responseLog[hk]) implies always Registry.responseLog[hk] = Registry.responseLog'[hk]
 )
}

check SR005_idempotency for 2 but 1..3 steps

pred SR005_assessment_retry {
 some at: AssessmentTarget, adr: AssessmentDataRevision,
  hk: HashKey, r: Response |
  eventually (
   no Registry.responseLog[hk]
   and registerAssessmentData[at, adr, hk]
   and Registry.responseLog'[hk] = r
   and after (
    Registry.responseLog[hk] = r
    and registerAssessmentData[at, adr, hk]
    and Registry.responseLog'[hk] = r
   )
  )
}

pred SR005_parameter_retry {
 some at: AssessmentTarget, psr: ParameterSetRevision,
  hk: HashKey, r: Response |
  eventually (
   no Registry.responseLog[hk]
   and registerParameterSet[at, psr, hk]
   and Registry.responseLog'[hk] = r
   and after (
    Registry.responseLog[hk] = r
    and registerParameterSet[at, psr, hk]
    and Registry.responseLog'[hk] = r
   )
  )
}

run SR005_assessment_retry
 for 2 but 1 AssessmentTarget, 1..3 steps
run SR005_parameter_retry
 for 2 but 1 AssessmentTarget, 1..3 steps

// SR006: After successful registration, the registered version must be retrievable
// If response is logged as successful, the revision must remain registered
assert SR006_retrievability {
 always (
  all hk: HashKey, r: Response |
   (some Registry.responseLog[hk] and Registry.responseLog[hk] = r and r.status = Success)
   implies (
    (some at: AssessmentTarget, adr: AssessmentDataRevision |
     r.revision = adr and adr in Registry.registeredAssessmentData[at])
    or
    (some at: AssessmentTarget, psr: ParameterSetRevision |
     r.revision = psr and psr in Registry.registeredParameterSet[at])
   )
 )
}

check SR006_retrievability for 2 but 1..3 steps

pred SR006_assessment_retrieval {
 eventually (some at: AssessmentTarget, adr: AssessmentDataRevision,
  hk: HashKey, r: Response |
  Registry.responseLog[hk] = r
  and r.status = Success
  and r.revision = adr
  and adr in Registry.registeredAssessmentData[at])
}

pred SR006_parameter_retrieval {
 eventually (some at: AssessmentTarget, psr: ParameterSetRevision,
  hk: HashKey, r: Response |
  Registry.responseLog[hk] = r
  and r.status = Success
  and r.revision = psr
  and psr in Registry.registeredParameterSet[at])
}

run SR006_assessment_retrieval
 for 2 but 1 AssessmentTarget, 1..3 steps
run SR006_parameter_retrieval
 for 2 but 1 AssessmentTarget, 1..3 steps

// SR007: Retrieval requests return the contents recorded in that version
// (Automatically satisfied because revision content is immutable)

pred SR007_assessment_by_revision {
 eventually (some at: AssessmentTarget, adr: AssessmentDataRevision,
  data: AssessmentData |
  adr in Registry.registeredAssessmentData[at]
  and data = adr.assessmentData)
}

pred SR007_parameter_by_revision {
 eventually (some at: AssessmentTarget, psr: ParameterSetRevision,
  params: ParameterSet |
  psr in Registry.registeredParameterSet[at]
  and params = psr.parameterSet)
}

run SR007_assessment_by_revision
 for 2 but 1 AssessmentTarget, 1..3 steps
run SR007_parameter_by_revision
 for 2 but 1 AssessmentTarget, 1..3 steps

// SR008: AssessmentData and ParameterSet each have at most one current revision
// (Enforced by the lone multiplicity of the current revision fields)

pred SR008_assessment_current {
 eventually (some at: AssessmentTarget,
  disj previousRevision, currentRevision: AssessmentDataRevision |
  previousRevision + currentRevision in Registry.registeredAssessmentData[at]
  and Registry.currentAssessmentData[at] = currentRevision)
}

pred SR008_parameter_current {
 eventually (some at: AssessmentTarget,
  disj previousRevision, currentRevision: ParameterSetRevision |
  previousRevision + currentRevision in Registry.registeredParameterSet[at]
  and Registry.currentParameterSet[at] = currentRevision)
}

run SR008_assessment_current
 for 3 but 1 AssessmentTarget, 1..3 steps
run SR008_parameter_current
 for 3 but 1 AssessmentTarget, 1..3 steps

// SR009: Successful registration makes the new revision current

pred SR009_assessment_advance {
 eventually (some at: AssessmentTarget,
  disj previousRevision, newRevision: AssessmentDataRevision,
  hk: HashKey |
  Registry.currentAssessmentData[at] = previousRevision
  and newRevision.previousSource = previousRevision
  and no Registry.responseLog[hk]
  and registerAssessmentData[at, newRevision, hk]
  and Registry.currentAssessmentData'[at] = newRevision)
}

pred SR009_parameter_advance {
 eventually (some at: AssessmentTarget,
  disj previousRevision, newRevision: ParameterSetRevision,
  hk: HashKey |
  Registry.currentParameterSet[at] = previousRevision
  and newRevision.previousSource = previousRevision
  and no Registry.responseLog[hk]
  and registerParameterSet[at, newRevision, hk]
  and Registry.currentParameterSet'[at] = newRevision)
}

run SR009_assessment_advance
 for 3 but 1 AssessmentTarget, 1..3 steps
run SR009_parameter_advance
 for 3 but 1 AssessmentTarget, 1..3 steps

// SR010: Past versions must not be modified or deleted even after a new version is registered
// (Automatically satisfied by operation design: registerAssessmentData/registerParameterSet only extend
//  the mapping with new versions; they never modify or remove existing entries)

pred SR010_assessment_history {
 eventually (some at: AssessmentTarget,
  disj previousRevision, newRevision: AssessmentDataRevision,
  hk: HashKey |
  Registry.currentAssessmentData[at] = previousRevision
  and previousRevision in Registry.registeredAssessmentData[at]
  and newRevision.previousSource = previousRevision
  and no Registry.responseLog[hk]
  and registerAssessmentData[at, newRevision, hk]
  and previousRevision + newRevision in Registry.registeredAssessmentData'[at]
  and Registry.currentAssessmentData'[at] = newRevision)
}

pred SR010_parameter_history {
 eventually (some at: AssessmentTarget,
  disj previousRevision, newRevision: ParameterSetRevision,
  hk: HashKey |
  Registry.currentParameterSet[at] = previousRevision
  and previousRevision in Registry.registeredParameterSet[at]
  and newRevision.previousSource = previousRevision
  and no Registry.responseLog[hk]
  and registerParameterSet[at, newRevision, hk]
  and previousRevision + newRevision in Registry.registeredParameterSet'[at]
  and Registry.currentParameterSet'[at] = newRevision)
}

run SR010_assessment_history
 for 3 but 1 AssessmentTarget, 1..3 steps
run SR010_parameter_history
 for 3 but 1 AssessmentTarget, 1..3 steps

/*  ============================================================
    6. Sanity
    ============================================================ */

run {} for 2 but 1..3 steps

Execute Allの結果:

21 commands were executed. The results are:
   #1: Instance found. SR001_registration is consistent.
   #2: Instance found. SR002_content_stability is consistent.
   #3: No counterexample found. SR003_new_version_on_change may be valid.
   #4: Instance found. SR003_assessment_update is consistent.
   #5: Instance found. SR003_parameter_update is consistent.
   #6: Instance found. SR004_revision_chain is consistent.
   #7: No counterexample found. SR005_idempotency may be valid.
   #8: Instance found. SR005_assessment_retry is consistent.
   #9: Instance found. SR005_parameter_retry is consistent.
   #10: No counterexample found. SR006_retrievability may be valid.
   #11: Instance found. SR006_assessment_retrieval is consistent.
   #12: Instance found. SR006_parameter_retrieval is consistent.
   #13: Instance found. SR007_assessment_by_revision is consistent.
   #14: Instance found. SR007_parameter_by_revision is consistent.
   #15: Instance found. SR008_assessment_current is consistent.
   #16: Instance found. SR008_parameter_current is consistent.
   #17: Instance found. SR009_assessment_advance is consistent.
   #18: Instance found. SR009_parameter_advance is consistent.
   #19: Instance found. SR010_assessment_history is consistent.
   #20: Instance found. SR010_parameter_history is consistent.
   #21: Instance found. run$21 is consistent.

↑ OK ✅

学んだこと

今回は反省点が多い。途中から雲行きの怪しさを感じていた。まとめると下記だ:

要件定義が雑すぎた
スコープを決めていなかった
進め方の戦略がなかった

要件定義が雑すぎた

一つ一つの要件の検証にかなり時間をかけているわけだが、そもそもそれぞれの要件自体の吟味が足りていないかった。要件をかっちり決める手法として、昔（確か2022年くらい）この本を読んだことでICONIXを知ったのだが、当時は重厚すぎるような印象を持っていた。

今回設計しているdata-registryは、構想当時にはとてもシンプルなものという見立てだったが、少し設計してみると考えるべきことがどんどん出てくる（なお今、この設計でも観点が全然足りていないだろう）。

スコープを決めていなかった

今回は合計で10要件を検証したように書いているが、実は途中でどんどん要件が増えてしまい、最終的に20を超えてしまっていた。収集がつかなくなりそうだったので、記事としてはいったん10の要件で一区切りとすることにした。ちなみに区切りとするために捨てた機能は「アーカイブ」「物理削除」「外部公開」の三つ。非機能要件としては並行性への対処を無視している。時間の関係から、そもそも「機能」「スコープ」について言及していない内容になってしまったが、このやり方は是非真似しないでほしい（？）。

進め方の戦略がなかった

これは上記二つの反省点と同列ではなく、より上位の観点にある。 Alloyで検証することが決まっているような形で走り始めてしまったため、Alloyでの検証に向かないような要件が出てきたときに管理できなくなった。今後の管理を考えると、サービスごとにユースケース・要求・要件にIDをふってドキュメント化しておくといいかもしれない。そろそろカンバンを作るか。

・・・

反省点は多いし、設計にまだ穴もあるだろうが、そろそろ動くものを作りたい。いや、その前に冪等性の定義とDB設計があるか。

作業の進捗としてはこんな感じだろうか:

API契約を書く
ルーティングの動作確認
db セットアップ
リポジトリ・ハンドラの実装
~~datasetVersion生成ロジックの設計~~
API基本設計
Revision生成ロジックの設計
データベース設計
リファクタリング
エラーハンドリングの追加

つづく

参考情報

Geewax (2022)『APIデザインパターン』マイナビ出版

たまたま『APIデザインパターン』を読んでいたのだった。第28章「リソースリビジョン」がドンピシャの内容だった ↩︎
『抽象によるソフトウェア設計』でも解説されており、特異な例を見つけるのに有用とされている。それはたしかにそうかも。ちなみに、このAlloyの挙動を決めているのは解析エンジンの挙動。私の環境ではSAT4Jソルバーだったので、SAT4Jのコードを見てみたところ、この部分によって、解決フェーズでまずfalseが試されそうだった ↩︎
Alloyによる探索が有限スコープなのは実用観点で脇に置いておく ↩︎

ユビキタス言語でデータ登録サービスを整理する

Sat, 01 Aug 2026 00:00:00 +0900

アプリケーションの設計を実際の資源評価事業のメンタルモデルが反映されたものにするために、資源評価事業で使うユビキタス言語を整理した。

はじめに

ユビキタス言語がないと、アプリケーションの仕様をちゃんとモデリングできない。例えばこの記事を書いた時点ではデータ登録サービスを作っていて、設計中に「データ」や「データセット」などの表現が混在してしまっていた。設計を整理する中で「メタデータ」なる表現も出てきたが、資源評価担当者だった当時を振り返っても、こんな表現を使ったことは一度もなかったように思う。

データ登録サービスを開発しようとしている現時点に限って言えば、いま必要なのは水産研究・教育機構が掲載している “用語集”にあるような、評価・管理観点の用語ではなく、データを扱う評価担当者が使っている用語だ。それゆえに対外的に公表されにくい¹。

ということで、本記事ではデータ登録サービスのユビキタス言語を整理していく。

設計に必要な用語の種類

用語の整理は、下記二つに分類する:

ドメイン語彙（ユビキタス言語）: 業務で実際に使われているもの
モデル語彙: 業務で使われることはないが、期待される動作を実現するためにモデリング上必要な語彙

前者は問題空間の用語、後者は解決空間の用語。

ドメイン語彙

用語	形式言語内での表現	意味
資源	Resource	評価対象となる種名と系群の組。例：「カタクチイワシ・太平洋系群」。日常会話では「カタクチ太平洋」のように略して呼ぶことがある
年度評価	AnnualAssessment	特定の年度に実施する資源評価。例：「2026年度評価」
評価対象	AssessmentTarget	年度評価と資源の組。例：「2026年度のカタクチ太平洋」
評価データ	AssessmentData	年度評価で利用するデータ。例：年齢別漁獲尾数、年齢別体重、年齢別成熟率
パラメータセット	ParameterSet	評価計算で使用するパラメータの集合
シナリオ	Scenario	評価作業中に比較・検討する論理的な単位。例：「昨年度踏襲」「手法A検討用」。シナリオは、使用する評価データやパラメータセットを参照する
版	Revision	評価データまたはパラメータセットの不変なスナップショット。内容を修正するときは、既存の版を変更せず、新しい版を作成する
最新版	CurrentRevision	評価データまたはパラメータセットについて、現在使用するものとして選択されている版
外部公開	Publish	評価データまたはパラメータセットの特定の版を、組織外から利用可能な状態にすること

モデル語彙

用語	形式言語内での表現	意味
アーカイブ	Archive	評価データ、パラメータセットまたはシナリオを通常の利用対象から外すこと。版の内容は保持する
物理削除	Erase	機密情報の誤登録などに対応するため、版に記録された内容そのものを削除すること
登録要求識別子	IdempotencyKey	同一の登録要求を識別するために、コンシューマーが登録要求に付与する識別子

まとめ

手元でのモデリングを進めるうえで必要だったので、ひとまずはこんなところでいいだろう。

確認のために「エヴァンス本」の第2章を読み返していたのだが、「高次の構成原理（コンテキストマップや大規模な構造など）」も、今後必要になったら整理したほうがいいかも。

参考情報

Eric Evans（2013）『エリック・エヴァンスのドメイン駆動設計』翔泳社（邦訳版）

公表されないのは機密的な問題ではなく、インセンティブの問題。内部で（何気なく）しか使わない専門表現をわざわざ整理して公開するインセンティブなどどこにもない。専門用語として認識されてすらいないこともある。 ↩︎

Articles on Rindrics Mumbles

データ登録処理に関する技術選定: Revision IDの生成アルゴリズム

背景

Tag "data-registry" | rindrics.com

要件

候補アルゴリズム

候補アルゴリズムの比較検討

連番（✘ 不採用）

方法A: データベースレベル

方法B: アプリケーションレベル

Snowflake ID（✘ 不採用）

UUID v7（✔ 採用）

同タイムスタンプ内における一意性違反リスク

所感

冪等性キー生成に関する技術選定: ハッシュアルゴリズム

はじめに

Tag "data-registry" | rindrics.com

背景

衝突確率に着目した一次選定

利用程度に関するパラメータ

ユーザー数

運用期間

ユーザーあたり並列計算数

バースト利用期間

リクエスト数の見積もり

その他の観点での比較

SHA256

BLAKE3

所感

冪等性の設計〜等値性の判定場所をユースケース駆動で決める

はじめに

イミュータブルなデータレジストリの設計とAlloyによる形式検証 | rindrics.com

冪等性が必要な理由

等値性の定義

ユースケースの明確化

リクエスト処理時のユースケース

並行リクエストを冪等に処理する

ネットワークエラーによる再試行で冪等性を保証する

データの内容は同じだが異なる親Revisionに対して登録する

複数の言語で実装されたクライアントからのリクエストを処理する

運用時のユースケース

識別キー計算仕様を変更する

複数の識別キー計算仕様に対応する

冪等性キーの生成場所と等値性の判定場所の決定

まとめ

（後日追記）

補足記事 "PfEingのアプローチで働こう"

これはなに

スライド各ページの補足

（タイトル）

（自己紹介）

kintone.com プラットフォームを提供 ~ われら Yakumo にござる | blog.cybozu.io

「やっていること」

「PfEingチームの働き方」

「損益分岐点がある」

「常に必要な自問」

「PfEingのアプローチ」

「気を抜くとかんたんに外れうる」

「どうしても断れない依頼」

「…現実世界はいろいろあるけど」

謝辞

『実践 プラットフォームエンジニアリング』を読んだ

どんな本か

個人的に目に止まったところ

第1章 プラットフォームエンジニアリングとは何か

プラットフォームはDevOpsにとどまらない（p.4）

第2章 ソフトウェア・デファインドのプロダクトとアーキテクチャ

1年後にプラットフォームがどう使われるかを予測するのは不可能（p.44）

ドメイン駆動プラットフォーム設計（p.54）

スムーズな開発者体験を実現するインフラコスト配賦（p.59）

手動プロセスによる機会損失（p.60）

組織固有のケイパビリティをk8sのAPI拡張でオーケストレーションする（p.62）

第3章 計測で導くプラットフォームエンジニアリングの成功

エンジニアリングプラットフォーム構築のデシジョンツリー（p.70）

プラットフォーム価値モデリング（p.77）

パフォーマンスメトリクス | オンボーディング時間（p.86）

エンジニアリングプラットフォームのプロダクトドメイン（p.91）

第4章 ガバナンス・コンプライアンス・信頼

IDプロバイダーソリューション（p.117）

第5章 進化するオブザーバービリティ

『実践プラットフォームエンジニアリング』を読んだ

第1章プラットフォームエンジニアリングとは何か

第2章ソフトウェア・デファインドのプロダクトとアーキテクチャ

第3章計測で導くプラットフォームエンジニアリングの成功

第4章ガバナンス・コンプライアンス・信頼

第5章進化するオブザーバービリティ

第6章ソフトウェア・デファインドなエンジニアリングプラットフォームの構築

第7章プラットフォームコントロールプレーンの基礎

第8章コントロールプレーンのサービスとエクステンション

第9章スケールを支えるアーキテクチャの変更

第10章プラットフォームプロダクトの進化

データ登録サービスの構築その1 | rindrics.com