osrlib.versioning

Schema and engine version stamping.

Every serialized model (saves, commands, events) stamps itself with these values from birth. SCHEMA_VERSION is the single monotonically increasing integer shared by saves, commands, and events — independent of the package version. Within a schema version, changes are additive only (new event types, new optional fields); renames, removals, and semantic changes bump it, and a loader migrates an older document forward (see osrlib.persistence). The engine version identifies exact rules behavior: identical replay outcomes are guaranteed only when the recorded and running engine versions match.

The stamped-document helpers wrap a payload with both versions and a kind string, so serialized artifacts (characters, parties, saves) share one envelope that check_document can vet before any payload field is trusted.

SCHEMA_VERSION module-attribute

SCHEMA_VERSION = 2

The current serialization schema version shared by saves, commands, and events.

Version 2 dropped the recovered-treasure ledger from the save payload: the end-of-adventure award is computed from the departure-snapshot valuation delta instead, so a save no longer needs to carry the ledger field. See MIGRATIONS for the 1 → 2 step that drops it from older saves on load.

check_document

check_document(document: Mapping[str, object], expected_kind: str) -> dict[str, object]

Vet a stamped document's envelope and return its payload.

Unknown extra keys in the envelope are ignored, per the additive-schema contract. A schema_version older than the current one is accepted and migrated in order (see osrlib.persistence); schema version 1 is the floor.

Parameters:

Name	Type	Description	Default
document	Mapping[str, object]	A mapping previously produced by stamp_document.	required
expected_kind	str	The kind the caller expects, e.g. "character".	required

Returns:

Type	Description
dict[str, object]	The document's payload.

Raises:

Type	Description
ContentValidationError	If the envelope is malformed (missing keys, wrong types) or the document's kind is not expected_kind.
SaveVersionError	If the document's schema_version is newer than this library understands.

engine_version

engine_version() -> str

Return the exact osrlib package version, for stamping into saves and replays.

Returns:

Type	Description
str	The installed package version as reported by package metadata.

stamp_document

stamp_document(kind: str, payload: Mapping[str, object]) -> dict[str, object]

Wrap a payload in the stamped-document envelope.

Parameters:

Name	Type	Description	Default
kind	str	The document kind, e.g. "character" or "party". Non-empty.	required
payload	Mapping[str, object]	The serialized model content.	required

Returns:

Type	Description
dict[str, object]	A dict with kind, schema_version, engine_version, and payload keys.

Raises:

Type	Description
ValueError	If kind is empty.