From 90a669914b3f6aacae2afe0160a84dc423cfd8c2 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 14 Jun 2026 00:47:41 +0100 Subject: [PATCH] Reconcile Python CultMesh predictions --- packages/cultcache-py/README.md | 22 ++++-- .../cultcache-py/src/cultmesh_py/__init__.py | 2 + .../cultcache-py/src/cultmesh_py/session.py | 67 ++++++++++++++++++- .../cultcache-py/src/cultnet_py/__init__.py | 2 + .../cultcache-py/src/cultnet_py/prediction.py | 21 ++++++ packages/cultcache-py/tests/test_cultcache.py | 55 +++++++++++++++ 6 files changed, 161 insertions(+), 8 deletions(-) create mode 100644 packages/cultcache-py/src/cultnet_py/prediction.py diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 713d4b6e..8cb9c2c6 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -210,12 +210,13 @@ python -m cultnet_py.interop_peer probe --runtime-id python-prober --discovery-p `cultmesh_py` includes a local cache-backed node, schema-v0 helpers for the CultMesh Verse catalog and peer exchange wire messages, local authority lease -checks, stream transport negotiation, and committed simulation fact documents: +checks, stream transport negotiation, committed simulation fact documents, and +local prediction reconciliation: ```python from cultcache_py import define_database_entry_type -from cultnet_py import CultNetRawClient -from cultmesh_py import CultMesh, CultMeshDiscoveryClient, peer_exchange_request +from cultnet_py import CultNetClientAuthorityScope, CultNetRawClient +from cultmesh_py import CultMesh, CultMeshDiscoveryClient, CultMeshGameSessionOptions, peer_exchange_request note_doc = define_database_entry_type("mesh.note", [("body", 0)]) node = CultMesh.start_node("mesh.cc", runtime_id="python-runtime") @@ -255,8 +256,16 @@ committed = facts.commit({ "hasQuorum": True, }) -session = CultMesh.create_game_session(node) +session = CultMesh.create_game_session( + node, + CultMeshGameSessionOptions( + client_authority_scopes=( + CultNetClientAuthorityScope("python-runtime", schema_ids=(note_doc.catalog_entry().schema_id,), key_prefix="input:python"), + ), + ), +) session_commits = session.submit_and_commit(observation.to_wire()) +prediction = session.predict(note_doc, "input:python:move", {"body": "predicted input"}) ``` ## Wire Parity @@ -286,8 +295,9 @@ Current receipts: - `packages/cultcache-py/tests/test_cultcache.py` covers Python CultMesh Verse catalog, peer exchange, authority lease, stream negotiation, CultNet helper shapes, raw snapshot/shard-log application, simulation claim hashing, - consensus aggregation, game-session fact commits, committed simulation fact - payload slots, and witness artifact bundle payload slots. + consensus aggregation, game-session fact commits, local prediction + reconciliation, committed simulation fact payload slots, and witness artifact + bundle payload slots. - `cultcache_py`, `cultnet_py`, and `cultmesh_py` ship `py.typed` markers so downstream type checkers can inspect the package surface instead of treating the runtime as an untyped xenos swamp. diff --git a/packages/cultcache-py/src/cultmesh_py/__init__.py b/packages/cultcache-py/src/cultmesh_py/__init__.py index 8e39aaff..24e7238c 100644 --- a/packages/cultcache-py/src/cultmesh_py/__init__.py +++ b/packages/cultcache-py/src/cultmesh_py/__init__.py @@ -5,6 +5,7 @@ from .session import ( CultMeshGameSession, CultMeshGameSessionOptions, CultMeshPrediction, + CultMeshSessionChange, ) from .simulation import ( SIMULATION_FACT_DOCUMENT_TYPE, @@ -45,6 +46,7 @@ __all__ = [ "CultMeshPeerCard", "CultMeshPeerCatalog", "CultMeshPrediction", + "CultMeshSessionChange", "CultMeshSimulationFact", "CultMeshSimulationFactCommit", "CultMeshSimulationFactCommitter", diff --git a/packages/cultcache-py/src/cultmesh_py/session.py b/packages/cultcache-py/src/cultmesh_py/session.py index a0ca3bbb..b4be771d 100644 --- a/packages/cultcache-py/src/cultmesh_py/session.py +++ b/packages/cultcache-py/src/cultmesh_py/session.py @@ -4,7 +4,14 @@ from dataclasses import dataclass from typing import Any from cultcache_py.documents import DocumentDefinition -from cultnet_py import CultNetSimulationConsensusOptions, CultNetSimulationObservationHub +from cultnet_py import ( + CultNetAppliedRecord, + CultNetClientAuthorityScope, + CultNetRawClient, + CultNetSimulationConsensusOptions, + CultNetSimulationObservationHub, + apply_shard_log_response, +) from .node import CultMeshNode from .simulation import ( @@ -19,16 +26,26 @@ from .wire import CultMeshAuthorityLeaseCatalog, CultMeshPeerCatalog, CultMeshVe @dataclass(frozen=True) class CultMeshPrediction: key: str + schema_id: str document: DocumentDefinition[Any] value: Any +@dataclass(frozen=True) +class CultMeshSessionChange: + schema_id: str + record_key: str + change_kind: str + value: Any | None = None + + @dataclass class CultMeshGameSessionOptions: verse_catalog: CultMeshVerseCatalog | None = None peer_catalog: CultMeshPeerCatalog | None = None authority_leases: CultMeshAuthorityLeaseCatalog | None = None consensus_options: CultNetSimulationConsensusOptions | None = None + client_authority_scopes: tuple[CultNetClientAuthorityScope, ...] = () @dataclass @@ -46,10 +63,40 @@ class CultMeshGameSession: ) self.fact_committer = CultMeshSimulationFactCommitter(self.node) self._committed_fact_ids: set[str] = set() + self._client_authority_scopes = tuple(options.client_authority_scopes) + self._predicted_keys: set[tuple[str, str]] = set() def predict(self, document: DocumentDefinition[Any], key: str, value: Any) -> CultMeshPrediction: + schema_id = document.catalog_entry().schema_id + if not any(scope.matches(self.node.runtime_id, schema_id, key) for scope in self._client_authority_scopes): + raise ValueError( + f"Runtime {self.node.runtime_id!r} does not have client prediction authority " + f"for schema {schema_id!r} key {key!r}" + ) self.node.put(document, key, value) - return CultMeshPrediction(key=key, document=document, value=value) + self._predicted_keys.add((schema_id, key)) + return CultMeshPrediction(key=key, schema_id=schema_id, document=document, value=value) + + def apply_shard_log_response(self, response: dict[str, Any]) -> list[CultMeshSessionChange]: + applied = apply_shard_log_response(self.node.cache, self.node.documents, response) + return self._reconcile_applied(applied) + + def sync_shard_log( + self, + client: CultNetRawClient, + *, + shard_id: str, + shard_epoch: int | None = None, + after_sequence: int = 0, + limit: int | None = None, + ) -> list[CultMeshSessionChange]: + response = client.fetch_shard_log( + shard_id=shard_id, + shard_epoch=shard_epoch, + after_sequence=after_sequence, + limit=limit, + ) + return self.apply_shard_log_response(response) def submit_observation(self, observation_or_message: dict[str, Any]) -> list[dict[str, Any]]: return self.observation_hub.submit(observation_or_message) @@ -73,3 +120,19 @@ class CultMeshGameSession: self._committed_fact_ids.add(fact_id) commits.append(commit) return commits + + def _reconcile_applied(self, applied: list[CultNetAppliedRecord]) -> list[CultMeshSessionChange]: + changes: list[CultMeshSessionChange] = [] + for record in applied: + key = (record.schema_id, record.record_key) + change_kind = record.change_kind + if key in self._predicted_keys and record.change_kind in {"added", "updated"}: + self._predicted_keys.remove(key) + change_kind = "reconciled" + changes.append(CultMeshSessionChange( + schema_id=record.schema_id, + record_key=record.record_key, + change_kind=change_kind, + value=record.value, + )) + return changes diff --git a/packages/cultcache-py/src/cultnet_py/__init__.py b/packages/cultcache-py/src/cultnet_py/__init__.py index d80b7103..4b71ffbc 100644 --- a/packages/cultcache-py/src/cultnet_py/__init__.py +++ b/packages/cultcache-py/src/cultnet_py/__init__.py @@ -18,6 +18,7 @@ from .messages import ( snapshot_request, witness_artifact_bundle, ) +from .prediction import CultNetClientAuthorityScope from .replication import ( CultNetAppliedRecord, apply_raw_document_record, @@ -36,6 +37,7 @@ __all__ = [ "CultNetDatabaseSubscription", "CultNetRawClient", "CultNetAppliedRecord", + "CultNetClientAuthorityScope", "CultNetSimulationConsensus", "CultNetSimulationConsensusOptions", "CultNetSimulationObservationHub", diff --git a/packages/cultcache-py/src/cultnet_py/prediction.py b/packages/cultcache-py/src/cultnet_py/prediction.py new file mode 100644 index 00000000..63e8e386 --- /dev/null +++ b/packages/cultcache-py/src/cultnet_py/prediction.py @@ -0,0 +1,21 @@ +from __future__ import annotations + +from dataclasses import dataclass + + +@dataclass(frozen=True) +class CultNetClientAuthorityScope: + owner_runtime_id: str + schema_ids: tuple[str, ...] = () + key_prefix: str | None = None + + def __post_init__(self) -> None: + if not self.owner_runtime_id.strip(): + raise ValueError("owner_runtime_id must be non-empty") + + def matches(self, runtime_id: str, schema_id: str, record_key: str) -> bool: + return ( + self.owner_runtime_id == runtime_id + and (not self.schema_ids or schema_id in self.schema_ids) + and (self.key_prefix is None or record_key.startswith(self.key_prefix)) + ) diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index c90f0406..15e505c8 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -20,6 +20,7 @@ from cultcache_py.benchmark import run_benchmark from cultcache_py.interop import read_note, write_note from cultnet_py import ( compute_simulation_claim_hash, + CultNetClientAuthorityScope, CultNetRawClient, CultNetSimulationConsensusOptions, apply_raw_snapshot, @@ -961,6 +962,60 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(stored.claim_hash, claim_hash) self.assertEqual(stored.witness_count, 2) + def test_cultmesh_game_session_prediction_requires_scope_and_reconciles_shard_log(self) -> None: + note_doc = define_database_entry_type( + "mesh.input", + [("body", 0)], + schema_id="mesh.input.v1", + ) + with tempfile.TemporaryDirectory() as tmp: + node = CultMesh.create_node(Path(tmp) / "prediction.cc", runtime_id="client-a") + node.register_document(note_doc) + session = CultMesh.create_game_session( + node, + CultMeshGameSessionOptions( + client_authority_scopes=( + CultNetClientAuthorityScope( + "client-a", + schema_ids=("mesh.input.v1",), + key_prefix="input:client-a", + ), + ) + ), + ) + + with self.assertRaisesRegex(ValueError, "does not have client prediction authority"): + session.predict(note_doc, "input:other", {"body": "nope"}) + + prediction = session.predict(note_doc, "input:client-a:move", {"body": "predicted"}) + put = document_put_raw( + message_id="authoritative", + key=prediction.key, + schema_id=prediction.schema_id, + stored_at="2026-06-13T00:00:00Z", + payload=note_doc.encode_payload({"body": "authoritative"}), + shard_id="inputs", + shard_epoch=1, + ) + changes = session.apply_shard_log_response({ + "schemaVersion": "cultnet.shard_log_response.v0", + "messageId": "inputs-log", + "shardId": "inputs", + "shardEpoch": 1, + "entries": [ + { + "sequence": 1, + "committedAt": "2026-06-13T00:00:00Z", + "changeKind": "updated", + "put": put.to_wire(), + } + ], + "resyncRequired": False, + }) + + self.assertEqual(changes[0].change_kind, "reconciled") + self.assertEqual(node.get_required(note_doc, prediction.key)["body"], "authoritative") + def test_cultmesh_verse_catalog_response_matches_schema_v0_wire_shape(self) -> None: import msgpack # type: ignore