game.gm.migration — ai.intergraph/game-master 0.1.34

The tools a cutover needs (mom/docs/phase-2/02-state-migration.md): prove that an import from MoM is faithful, and write the GM's state back into MoM's shape so the routed path stays a real fallback after the GM has taken writes.

• diff-state compares a MoM export with what is in the store. It is for checking an IMPORT: protocol rows must match exactly, so run it before the GM takes writes.
• import-checked! imports into an EMPTY store and refuses to leave a bad import unreported.
• reverse-state rebuilds a MoM-shaped state (protocol rows, the progress token under :gm, the :idempotency map from the receipts) from the store.
• rollback-write! writes the store back into MoM and VERIFIES it by reading MoM's copy back. It refuses an empty store (that would erase MoM's copy) and refuses to report success unless MoM now holds what the store holds.
• fetch-export! / push-state! / require-frozen-and-drained! are the thin MoM calls. Anything that writes demands that MoM report the game frozen and drained first.

diff-state clj

(diff-state export store*)

Compares a MoM export with the store: {:ok? bool :differences [..] :summary {..}}. Both sides go through the JSON round trip a handler sees. Differences, by :kind: :missing-in-store / :extra-in-store {:protocol}, :changed {:protocol :paths [..]} (the first few differing paths), :token-behind {:export :store} (the store's progress token must be at least the export's), :receipts-missing {:ids} (every legacy :idempotency entry must have become a receipt; the store may have more).

fetch-export! clj

(fetch-export! mom-url game-name)

MoM's export of the game's state (GET /api/v1/storage/game/:g/reload): the :state map. Needs the GM's own credential and a valid GM lease.

freeze-status clj

(freeze-status mom-url game-name)

MoM's freeze status for the game: {:frozen bool :in-flight n ...}.

import-checked! clj

(import-checked! s export)

Imports a MoM export into s, which must be EMPTY (import-state! wipes the store), then diffs it. Throws {:error :store-not-empty} before touching anything, or {:error :import-mismatch :report r} if the result does not match the export. Returns the clean report.

push-state! clj

(push-state! mom-url game-name state)

Writes state as the game's state in MoM (POST /api/v1/storage/game/:g/kv, an unconditional save): the rollback write. Callers must have checked require-frozen-and-drained!.

require-frozen-and-drained! clj

(require-frozen-and-drained! mom-url game-name)

Throws unless MoM reports the game frozen with no events in flight. The in-flight count is per MoM instance: with more than one MoM task, check each. Returns the status.

reverse-state clj

(reverse-state s)

The store's state in MoM's shape: protocol rows, the latest progress token under [:gm :progress-token], and :idempotency rebuilt from the receipts. What push-state! writes back to MoM for a rollback.

rollback-write! clj

(rollback-write! s mom-url game-name)

Writes the store's state back into MoM (the rollback of a runtime v2 game) and checks the result by reading MoM's copy back and diffing it against the store. Returns the clean report. Throws, and a caller must treat either as a failed rollback: {:error :store-empty} BEFORE writing anything: an empty store written back would erase the game's state in MoM {:error :rollback-mismatch :report r} after the write, MoM does not hold what the store holds (for example MoM accepted the write and kept nothing, as its /kv route did before mom #60). The game's state in MoM is then NOT the store's: do not unfreeze it. A MoM that refuses the write still throws {:error :mom-request-failed} from push-state!.

store-empty? clj

(store-empty? s)