diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index af9d3dfb..7e5344a8 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -24,6 +24,9 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. - Python CultMesh database facade: `node.database` owns the local typed document read/write/snapshot/sync surface so Python callers do not need to reach through the node composition wrapper. + It also exposes local `watch(...)` / `watch_record(...)` callbacks for database + changes, including authoritative shard-log reconciliation applied through the + session facade. - Python CultMesh committed simulation facts: The live interop harness sends Python a simulation observation, receives a consensus candidate, then requests the committed `gamecult.mesh.simulation_fact` diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 99d0baa4..b1f32a95 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -224,6 +224,7 @@ from cultmesh_py import CultMesh, CultMeshGameSessionOptions, peer_exchange_requ note_doc = define_database_entry_type("mesh.note", [("body", 0)]) node = CultMesh.start_node("mesh.cc", runtime_id="python-runtime") node.database.register_document(note_doc) +unsubscribe = node.database.watch_record(note_doc, "note:1", lambda change: print(change.change_kind)) node.database.put(note_doc, "note:1", {"body": "hello"}) live_note = node.database.get_required(note_doc, "note:1") put_message = node.database.put_raw_message(note_doc, "note:2", {"body": "wire me"}, shard_id="interop", shard_epoch=1) @@ -269,6 +270,7 @@ session = CultMesh.create_game_session( ) session_commits = session.submit_and_commit(observation.to_wire()) prediction = session.predict(note_doc, "input:python:move", {"body": "predicted input"}) +unsubscribe() ``` ## Wire Parity diff --git a/packages/cultcache-py/src/cultcache_py/verify.py b/packages/cultcache-py/src/cultcache_py/verify.py index e7e6b1f0..0b4bb4af 100644 --- a/packages/cultcache-py/src/cultcache_py/verify.py +++ b/packages/cultcache-py/src/cultcache_py/verify.py @@ -30,6 +30,7 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = { "cultmesh_py": ( "CultMesh", "CultMeshDatabase", + "CultMeshDatabaseChange", "CultMeshGameSession", "CultMeshPeerExchangeClient", "CultMeshSimulationFact", diff --git a/packages/cultcache-py/src/cultmesh_py/__init__.py b/packages/cultcache-py/src/cultmesh_py/__init__.py index 25b9ca4d..932d921b 100644 --- a/packages/cultcache-py/src/cultmesh_py/__init__.py +++ b/packages/cultcache-py/src/cultmesh_py/__init__.py @@ -1,6 +1,6 @@ from .client import CultMeshDiscoveryClient, CultMeshPeerExchangeClient, CultMeshVerseDiscoveryClient from .facade import CultMesh -from .node import CultMeshDatabase, CultMeshNode, create_node +from .node import CultMeshDatabase, CultMeshDatabaseChange, CultMeshNode, create_node from .session import ( CultMeshGameSession, CultMeshGameSessionOptions, @@ -41,6 +41,7 @@ from .wire import ( __all__ = [ "CultMeshNode", "CultMeshDatabase", + "CultMeshDatabaseChange", "CultMesh", "CultMeshGameSession", "CultMeshGameSessionOptions", diff --git a/packages/cultcache-py/src/cultmesh_py/node.py b/packages/cultcache-py/src/cultmesh_py/node.py index 811ad35f..9313e5bc 100644 --- a/packages/cultcache-py/src/cultmesh_py/node.py +++ b/packages/cultcache-py/src/cultmesh_py/node.py @@ -2,7 +2,7 @@ from __future__ import annotations from dataclasses import dataclass, field from pathlib import Path -from typing import Any +from typing import Any, Callable from cultcache_py import CultCache, CultCacheEnvelope, SingleFileMessagePackBackingStore from cultcache_py.documents import DocumentDefinition @@ -10,13 +10,24 @@ from cultnet_py import ( CultNetAppliedRecord, CultNetMessage, CultNetRawClient, - apply_raw_snapshot, - apply_shard_log_response, + apply_raw_snapshot as apply_cultnet_raw_snapshot, + apply_shard_log_response as apply_cultnet_shard_log_response, document_delete, document_put_raw, + schema_document_map, ) +@dataclass(frozen=True) +class CultMeshDatabaseChange: + document: DocumentDefinition[Any] + schema_id: str + record_key: str + change_kind: str + value: Any | None = None + previous_value: Any | None = None + + @dataclass class CultMeshNode: cache: CultCache = field(default_factory=CultCache) @@ -122,6 +133,7 @@ class CultMeshNode: class CultMeshDatabase: def __init__(self, node: CultMeshNode) -> None: self._node = node + self._subscribers: list[tuple[DocumentDefinition[Any] | None, str | None, Callable[[CultMeshDatabaseChange], None]]] = [] @property def cache(self) -> CultCache: @@ -135,12 +147,38 @@ class CultMeshDatabase: def runtime_id(self) -> str: return self._node.runtime_id + def watch( + self, + callback: Callable[[CultMeshDatabaseChange], None], + *, + document: DocumentDefinition[Any] | None = None, + key: str | None = None, + ) -> Callable[[], None]: + subscriber = (document, key, callback) + self._subscribers.append(subscriber) + + def unsubscribe() -> None: + if subscriber in self._subscribers: + self._subscribers.remove(subscriber) + + return unsubscribe + + def watch_record( + self, + document: DocumentDefinition[Any], + key: str, + callback: Callable[[CultMeshDatabaseChange], None], + ) -> Callable[[], None]: + return self.watch(callback, document=document, key=key) + def register_document(self, document: DocumentDefinition[Any]) -> None: self.cache.register_document_type(document) self.documents.append(document) def put(self, document: DocumentDefinition[Any], key: str, value: Any) -> None: + previous = self.cache.get(document, key) self.cache.put(document, key, value) + self._publish_local_change(document, key, "added" if previous is None else "updated", value, previous) def put_raw_message( self, @@ -153,6 +191,7 @@ class CultMeshDatabase: shard_epoch: int | None = None, ) -> CultNetMessage: catalog_entry = document.catalog_entry() + previous = self.cache.get(document, key) envelope = CultCacheEnvelope.create( key=key, type=document.type, @@ -160,7 +199,8 @@ class CultMeshDatabase: schema_id=catalog_entry.schema_id, catalog_entry=catalog_entry, ) - self.cache.put_envelope(document, envelope) + value = self.cache.put_envelope(document, envelope) + self._publish_local_change(document, key, "added" if previous is None else "updated", value, previous) return document_put_raw( message_id=message_id, key=key, @@ -179,7 +219,10 @@ class CultMeshDatabase: return self.cache.get_required(document, key) def delete(self, document: DocumentDefinition[Any], key: str) -> None: + previous = self.cache.get(document, key) self.cache.delete(document, key) + if previous is not None: + self._publish_local_change(document, key, "removed", None, previous) def delete_raw_message( self, @@ -221,7 +264,7 @@ class CultMeshDatabase: shard_id=shard_id, shard_epoch=shard_epoch, ) - return apply_raw_snapshot(self.cache, self.documents, response) + return self.apply_snapshot_response(response) def sync_shard_log( self, @@ -238,7 +281,56 @@ class CultMeshDatabase: after_sequence=after_sequence, limit=limit, ) - return apply_shard_log_response(self.cache, self.documents, response) + return self.apply_shard_log_response(response) + + def apply_snapshot_response(self, response: dict[str, Any]) -> list[CultNetAppliedRecord]: + applied = apply_cultnet_raw_snapshot(self.cache, self.documents, response) + self._publish_applied_records(applied) + return applied + + def apply_shard_log_response(self, response: dict[str, Any]) -> list[CultNetAppliedRecord]: + applied = apply_cultnet_shard_log_response(self.cache, self.documents, response) + self._publish_applied_records(applied) + return applied + + def _publish_local_change( + self, + document: DocumentDefinition[Any], + key: str, + change_kind: str, + value: Any | None, + previous: Any | None, + ) -> None: + self._publish(CultMeshDatabaseChange( + document=document, + schema_id=document.catalog_entry().schema_id, + record_key=key, + change_kind=change_kind, + value=value, + previous_value=previous, + )) + + def _publish_applied_records(self, applied: list[CultNetAppliedRecord]) -> None: + documents_by_schema_id = schema_document_map(self.documents) + for record in applied: + document = documents_by_schema_id.get(record.schema_id) + if document is None: + continue + self._publish(CultMeshDatabaseChange( + document=document, + schema_id=record.schema_id, + record_key=record.record_key, + change_kind=record.change_kind, + value=record.value, + )) + + def _publish(self, change: CultMeshDatabaseChange) -> None: + for document, key, callback in list(self._subscribers): + if document is not None and document.type != change.document.type: + continue + if key is not None and key != change.record_key: + continue + callback(change) def create_node(cache_path: str | Path | None = None, *, runtime_id: str = "python-runtime") -> CultMeshNode: diff --git a/packages/cultcache-py/src/cultmesh_py/session.py b/packages/cultcache-py/src/cultmesh_py/session.py index b4be771d..875a5c87 100644 --- a/packages/cultcache-py/src/cultmesh_py/session.py +++ b/packages/cultcache-py/src/cultmesh_py/session.py @@ -10,7 +10,6 @@ from cultnet_py import ( CultNetRawClient, CultNetSimulationConsensusOptions, CultNetSimulationObservationHub, - apply_shard_log_response, ) from .node import CultMeshNode @@ -78,7 +77,7 @@ class CultMeshGameSession: 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) + applied = self.node.database.apply_shard_log_response(response) return self._reconcile_applied(applied) def sync_shard_log( diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index 4dd61d19..2e9f0815 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -48,6 +48,7 @@ from cultmesh_py import create_node from cultmesh_py import ( CultMesh, CultMeshDatabase, + CultMeshDatabaseChange, CultMeshGameSessionOptions, CultMeshPeerCard, CultMeshPeerCatalog, @@ -878,6 +879,30 @@ class CultCacheTests(unittest.TestCase): reopened.database.pull() self.assertEqual(reopened.database.get(document, "note:1")["body"], "hello") + def test_cultmesh_database_watchers_observe_local_changes_and_unsubscribe(self) -> None: + document = define_database_entry_type("mesh.watch", [("body", 0)]) + node = CultMesh.create_node(runtime_id="mesh-watch") + node.database.register_document(document) + changes: list[CultMeshDatabaseChange] = [] + all_changes: list[CultMeshDatabaseChange] = [] + + unsubscribe_record = node.database.watch_record(document, "note:1", changes.append) + unsubscribe_all = node.database.watch(all_changes.append, document=document) + + node.database.put(document, "note:1", {"body": "hello"}) + node.database.put(document, "note:2", {"body": "skip"}) + node.database.put(document, "note:1", {"body": "updated"}) + node.database.delete(document, "note:1") + unsubscribe_record() + node.database.put(document, "note:1", {"body": "after-unsubscribe"}) + unsubscribe_all() + + self.assertEqual([change.change_kind for change in changes], ["added", "updated", "removed"]) + self.assertEqual([change.record_key for change in changes], ["note:1", "note:1", "note:1"]) + self.assertEqual(changes[1].previous_value, {"body": "hello"}) + self.assertIsNone(changes[2].value) + self.assertEqual([change.record_key for change in all_changes], ["note:1", "note:2", "note:1", "note:1", "note:1"]) + def test_cultmesh_facade_matches_peer_runtime_entrypoints(self) -> None: with tempfile.TemporaryDirectory() as tmp: store_path = Path(tmp) / "mesh.cc" @@ -1120,6 +1145,59 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(changes[0].change_kind, "reconciled") self.assertEqual(node.get_required(note_doc, prediction.key)["body"], "authoritative") + def test_cultmesh_database_watchers_observe_authoritative_shard_log_reconciliation(self) -> None: + note_doc = define_database_entry_type( + "mesh.watched_input", + [("body", 0)], + schema_id="mesh.watched_input.v1", + ) + node = CultMesh.create_node(runtime_id="client-watch") + node.database.register_document(note_doc) + seen: list[CultMeshDatabaseChange] = [] + node.database.watch_record(note_doc, "input:client-watch:move", seen.append) + session = CultMesh.create_game_session( + node, + CultMeshGameSessionOptions( + client_authority_scopes=( + CultNetClientAuthorityScope( + "client-watch", + schema_ids=("mesh.watched_input.v1",), + key_prefix="input:client-watch", + ), + ) + ), + ) + + prediction = session.predict(note_doc, "input:client-watch:move", {"body": "predicted"}) + put = document_put_raw( + message_id="authoritative-watch", + 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, + ) + session_changes = session.apply_shard_log_response({ + "schemaVersion": "cultnet.shard_log_response.v0", + "messageId": "inputs-watch-log", + "shardId": "inputs", + "shardEpoch": 1, + "entries": [ + { + "sequence": 1, + "committedAt": "2026-06-13T00:00:00Z", + "changeKind": "updated", + "put": put.to_wire(), + } + ], + "resyncRequired": False, + }) + + self.assertEqual([change.change_kind for change in seen], ["added", "updated"]) + self.assertEqual(seen[1].value, {"body": "authoritative"}) + self.assertEqual(session_changes[0].change_kind, "reconciled") + def test_cultmesh_verse_catalog_response_matches_schema_v0_wire_shape(self) -> None: import msgpack # type: ignore