Add Python CultMesh database watchers

This commit is contained in:
Meta Vens 2026-06-14 02:03:44 +01:00
commit 473bece217
7 changed files with 185 additions and 9 deletions

View file

@ -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`

View file

@ -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

View file

@ -30,6 +30,7 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = {
"cultmesh_py": (
"CultMesh",
"CultMeshDatabase",
"CultMeshDatabaseChange",
"CultMeshGameSession",
"CultMeshPeerExchangeClient",
"CultMeshSimulationFact",

View file

@ -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",

View file

@ -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:

View file

@ -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(

View file

@ -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