mstar.model.cosmos3.sessions

mstar.model.cosmos3.sessions#

Per-session world state for windowed rollouts.

A session_id on a windowed request names a world the client may come back to (resume_session). The DiT node keeps the rollout’s last window under it and the streaming decoder its decode context, each in a SessionStore. The store is bounded and LRU-ordered, and it knows which sessions have a request in flight: those are never evicted and refuse a second request, so two rollouts cannot write the same world at once. Idle sessions expire after their timeout, so a client that crashes mid-rollout does not leave a state behind forever.

Classes

SessionStore(capacity, default_ttl_s, max_ttl_s)

Bounded, LRU-ordered session state with in-flight pins and a TTL.
class mstar.model.cosmos3.sessions.SessionStore(capacity, default_ttl_s, max_ttl_s, clock=time.monotonic)[source]#

Bases: object

Bounded, LRU-ordered session state with in-flight pins and a TTL.

A request that names a session begin``s it, which pins it for the request's duration (a second request on a live session is refused), reads the stored state with ``get (which promotes it, so every node’s store ages the same way), and either put``s the new state when it is done or ``end``s the session. ``release unpins whatever a removed request held. Only idle sessions count against capacity and can be evicted (expired ones first, then the oldest); live ones never are, so the store holds at most capacity idle plus the in-flight sessions.

Parameters:
begin(session_id, request_id)[source]#

Pin session_id for request_id until it stores or ends the session (or is removed). Refused while another request holds it.

Parameters:

  • session_id (str)

  • request_id (str)

Return type:

None

end(session_id)[source]#

Forget the session, stored state and pin alike.

Parameters:

session_id (str)

Return type:

None

get(session_id)[source]#

The stored state, promoting the session; None when the session is unknown, expired or has not stored anything yet.

Parameters:

session_id (str)

Return type:

Any | None

ids()[source]#

Sessions in LRU order, oldest first.

Return type:

list[str]

live(session_id)[source]#

The request generating under the session, if any.

Parameters:

session_id (str)

Return type:

str | None

put(session_id, value, ttl_s=None)[source]#

Store the session’s state and unpin it: the request under it is done with the session. Idle sessions over capacity go, oldest first.

Parameters:
Return type:

None

release(request_id)[source]#

Unpin whatever request_id holds (the request was removed before it stored or ended its session). A session it never stored goes.

Parameters:

request_id (str)

Return type:

None

ttl(requested)[source]#

A request’s session timeout: the default when unset, else clamped to the served maximum.

Parameters:

requested (float | None)

Return type:

float