game.gm.runtime-v2 — ai.intergraph/game-master 0.1.31

gm-lib runtime v2: the direct event endpoint a GM serves itself.

An event goes seat token -> idempotency receipt -> unchanged dispatch -> ONE transaction (state + receipt + journal + outbox rows) -> the event's effects run (ledger calls to MoM) -> response with no MoM routing. The handler contract is unchanged: a handler is given the whole state and returns :updated-state plus :effects; only what runs underneath it changed (see game.gm.store, game.gm.outbox, game.gm.seat-token).

WHO IS CALLING comes only from the verified seat token and MoM's seat lookup, never from the request body: a :caller, :game-state or :player/name in the body is ignored. STATE comes only from the store.

WHAT A SEAT MAY SEND is limited here, because MoM no longer sits in front of the event. Legacy protocols read the acting player and the caller's roles from event/data and some check no caller, so for a seat caller (never for the GM's own service-event!): bind-actor refuses an event naming another player and replaces any roles with the seat's real ones, and service-only-event? refuses the event types only the GM's own code may send (withdrawal/* by default). Always on: this is MoM's bind-actor and service-only-event?, without the observe mode.

A FAILED HANDLER RESULT PERSISTS NOTHING. MoM's router saves a failing handler's :updated-state best-effort; v2 treats a failure as "nothing happened" and records only a journal entry.

A QUERY (a result with no progress token: dispatch stamps one on every non-query event) writes no journal entry and no receipt.

AN EFFECT THAT IS STILL :pending in the response is not a failure: MoM's answer was uncertain and the outbox sweeper owns it until the ledger says yes or no.

create! clj

(create! {:keys [sweep-interval-ms] :as opts})

Builds the context, sweeps the outbox now (recovering whatever a previous process left behind) and every :sweep-interval-ms after (default 5 s) on a daemon thread. Returns {:ctx :handler :state-handler :stop!}; stop! stops the worker.

default-retention clj

How long the store keeps what only ever grows (see game.gm.store/prune!). Receipts: an event idempotency key reused after this long re-runs its event. Ledger effects are kept longest; MoM's ledger remembers its own keys either way.

default-service-only clj

Event types a seat may not send; only the GM's own code may (service-event!). Mirrors MoM's service-only-event?: the withdrawal protocol takes its actor and roles from event data and checks no caller, so a seat holder could move another player's or the house account's funds. withdrawal/query reads only the caller's own records.

default-sweep-interval-ms clj

handle-event! clj

(handle-event! {:keys [seat-opts] :as ctx} {:keys [token body]})

Handles one event: {:token <seat token> :body <event map>} -> {:status n :body m} (plain data, no Ring). The body is the event as a keyword-keyed map: :event/type, :event/data, optionally :event/version and :idempotency-key.

handle-seat-event! clj

(handle-seat-event! ctx {:keys [caller body]})

Handles an event from a seat the CALLER OF THIS FUNCTION has already authenticated: {:caller <envelope> :body <event map>} -> {:status n :body m}. The envelope is the shape MoM's seat lookup returns (:membership-id :player-name :roles :game-id). For a GM whose own web layer verified the user and the seat with MoM (the-js's UI /events route), so no seat token is involved. Everything else is identical to handle-event!, including the caller protections (service-only events, actor binding).

make-ctx clj

(make-ctx {:keys [store dispatch-fn seat-opts gm-id http-post now-fn log-fn
                  lease-ms player-memory-fn memory-protocols executors
                  callback-event-fn retention prune-interval-ms service-only
                  protected-protocols]})

The context the functions above take.

Required: :store, :dispatch-fn (payload -> handler result: in the-js, handlers/dispatch-gm-handler), :seat-opts {:mom-url :game-id :game-name}, :gm-id. Optional: :http-post, :now-fn, :log-fn, :lease-ms (see game.gm.outbox); :executors ({effect-type executor}, merged over the built-in ledger/batch and player/notify ones: a GM's other external calls, see game.gm.outbox DELIVERY) and :callback-event-fn; :service-only ({:prefixes [..] :except #{..}}, replacing default-service-only: the event types a seat may not send); :protected-protocols (protocols read-state-for-seat does not serve to players); :retention (overrides over default-retention, or false for none) and :prune-interval-ms; :player-memory-fn (caller -> the seat's private memory) with :memory-protocols (a set of protocol keywords, e.g. #{:attention}) to attach :player/memory to those events.

read-game-state clj

(read-game-state {:keys [store]})

The whole state, in the shape MoM's /api/v1/storage/game/:g/reload returns ({:success true :state ..}), for the GM's own state reads.

read-state-for-seat clj

(read-state-for-seat {:keys [seat-opts store protected-protocols] :as ctx}
                     {:keys [token]})

The whole current state for an authenticated seat: {:token t} -> {:status 200 :body {:success true :state ..}}, or the authentication error. What MoM's push used to embed in every notification (its public-game-state), now current: an agent woken by an inbox item reads this instead of trusting a snapshot taken at push time. Protocols named in :protected-protocols are left out. Read-only: nothing is written.

ring-handler clj

(ring-handler ctx)

A Ring handler for POST with Authorization: Bearer <seat token> and the event as the (keyword-keyed) body. An Idempotency-Key header is used when the body carries no :idempotency-key of its own. The app mounts it, e.g. at /v2/events.

service-event! clj

(service-event! {:keys [seat-opts] :as ctx}
                {:keys [event-type player-name roles data idempotency-key]})

The GM's own event, run locally: what submit-service-event did through MoM, minus MoM. {:event-type :player-name :roles :data}, acting AS player-name with roles through the same :event/data fields. There is no seat and no token: the caller is a system envelope, so only handlers that do not demand a membership are reachable this way (as through MoM's service credentials today). Returns MoM's envelope.

state-handler clj

(state-handler ctx)

A Ring handler for GET with Authorization: Bearer <seat token>: the current state (see read-state-for-seat). The app mounts it next to the events handler, e.g. at /v2/state.