From 09ec185355f353b74e35d2ff26b527800f3b139b Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 14 Jun 2026 13:26:51 +0100 Subject: [PATCH] Schedule Python observation fanout --- packages/cultcache-py/PARITY.md | 7 +- .../cultcache-py/src/cultmesh_py/__init__.py | 8 +- .../cultcache-py/src/cultmesh_py/client.py | 76 +++++++++++++++- packages/cultcache-py/tests/test_cultcache.py | 90 +++++++++++++++++++ .../Contracts/cultnet-distributed-database.md | 7 +- 5 files changed, 180 insertions(+), 8 deletions(-) diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index 2b3c720a..a1bd9a12 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -80,9 +80,10 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. from endpoint lists, de-duplicate discovery targets, fan out one-shot discovery from endpoints already advertised in local Verse and peer catalogs, fan out raw snapshot fetches and simulation observations to peer-card - endpoints, apply peer snapshots through a caller-owned database, and upsert - results into local catalogs with the same count-returning ergonomics as the - C# discovery clients. + endpoints, apply peer snapshots through a caller-owned database, run a + lightweight scheduled simulation-observation fanout loop, and upsert results + into local catalogs with the same count-returning ergonomics as the C# + discovery clients. - Python CultMesh facade: Exposes C#-matching client entrypoints for Verse discovery, peer exchange, raw CultNet client construction, local nodes, catalogs, sessions, streams, diff --git a/packages/cultcache-py/src/cultmesh_py/__init__.py b/packages/cultcache-py/src/cultmesh_py/__init__.py index fe0b5665..53c38c9e 100644 --- a/packages/cultcache-py/src/cultmesh_py/__init__.py +++ b/packages/cultcache-py/src/cultmesh_py/__init__.py @@ -1,4 +1,9 @@ -from .client import CultMeshDiscoveryClient, CultMeshPeerExchangeClient, CultMeshVerseDiscoveryClient +from .client import ( + CultMeshDiscoveryClient, + CultMeshPeerExchangeClient, + CultMeshSimulationObservationFanout, + CultMeshVerseDiscoveryClient, +) from .facade import CultMesh from .node import CultMeshDatabase, CultMeshDatabaseChange, CultMeshNode, CultMeshNodeOptions, create_node from .server import CultMeshLocalServer @@ -63,6 +68,7 @@ __all__ = [ "AuthorityLeaseVerifier", "CultMeshDiscoveryClient", "CultMeshPeerExchangeClient", + "CultMeshSimulationObservationFanout", "CultMeshVerseDiscoveryClient", "CultMeshStreamCatalog", "CultMeshStreamConsumerProfile", diff --git a/packages/cultcache-py/src/cultmesh_py/client.py b/packages/cultcache-py/src/cultmesh_py/client.py index 56adb1a7..fe79ddb4 100644 --- a/packages/cultcache-py/src/cultmesh_py/client.py +++ b/packages/cultcache-py/src/cultmesh_py/client.py @@ -1,6 +1,7 @@ from __future__ import annotations -from dataclasses import dataclass +import threading +from dataclasses import dataclass, field from typing import Any, Callable from urllib.parse import urlparse @@ -351,6 +352,79 @@ class CultMeshPeerExchangeClient(CultMeshDiscoveryClient): return self.fanout_peer_catalog(catalog, verse_id=verse_id, roles=roles, limit=limit) +@dataclass +class CultMeshSimulationObservationFanout: + client: CultMeshDiscoveryClient + peer_catalog: CultMeshPeerCatalog + verse_id: str + roles: list[str] | None = None + interval_seconds: float = 1.0 + on_candidate: Callable[[dict[str, Any]], None] | None = None + on_error: Callable[[str, Exception], None] | None = None + _pending: list[dict[str, Any]] = field(default_factory=list, init=False, repr=False) + _lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False) + _stop: threading.Event = field(default_factory=threading.Event, init=False, repr=False) + _thread: threading.Thread | None = field(default=None, init=False, repr=False) + + def enqueue(self, message: dict[str, Any]) -> None: + with self._lock: + self._pending.append(dict(message)) + + def pending_count(self) -> int: + with self._lock: + return len(self._pending) + + def flush(self) -> list[dict[str, Any]]: + with self._lock: + messages = list(self._pending) + self._pending.clear() + candidates = [] + failed_messages: list[dict[str, Any]] = [] + for message in messages: + try: + candidates.extend(self.client.fanout_simulation_observation( + self.peer_catalog, + message, + verse_id=self.verse_id, + roles=self.roles, + on_error=self.on_error, + )) + except Exception: + failed_messages.append(message) + continue + if failed_messages: + with self._lock: + self._pending = [*failed_messages, *self._pending] + for candidate in candidates: + if self.on_candidate is not None: + self.on_candidate(candidate) + return candidates + + def start(self) -> "CultMeshSimulationObservationFanout": + if self._thread is not None: + return self + self._stop.clear() + self._thread = threading.Thread(target=self._run, daemon=True) + self._thread.start() + return self + + def stop(self) -> None: + self._stop.set() + if self._thread is not None: + self._thread.join(timeout=max(2.0, self.interval_seconds * 2.0)) + self._thread = None + + def __enter__(self) -> "CultMeshSimulationObservationFanout": + return self.start() + + def __exit__(self, exc_type: Any, exc: Any, traceback: Any) -> None: + self.stop() + + def _run(self) -> None: + while not self._stop.wait(self.interval_seconds): + self.flush() + + def _parse_endpoint(endpoint: str) -> tuple[str, int]: if not endpoint or not endpoint.strip(): raise ValueError("endpoint must be non-empty") diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index b4f36d85..ac3a3cf8 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -90,6 +90,7 @@ from cultmesh_py import ( CultMeshHmacAuthorityLeaseVerifier, CultMeshDiscoveryClient, CultMeshPeerExchangeClient, + CultMeshSimulationObservationFanout, CultMeshStreamCatalog, CultMeshStreamConsumerProfile, CultMeshStreamDescriptor, @@ -2554,6 +2555,95 @@ class CultCacheTests(unittest.TestCase): self.assertEqual({candidate["messageId"] for candidate in candidates}, {"fanout-observation"}) self.assertEqual({candidate["hasQuorum"] for candidate in candidates}, {True}) + def test_cultmesh_simulation_observation_fanout_flushes_queued_messages(self) -> None: + hub = CultNetSimulationObservationHub( + CultNetSimulationConsensusOptions(minimum_witnesses=1, quorum_ratio=1.0) + ) + server = CultMesh.serve_node(CultMesh.create_node(runtime_id="sim-flush-peer"), observation_hub=hub) + try: + peers = CultMeshPeerCatalog() + peers.upsert(CultMeshPeerCard( + peer_id="sim-flush-peer", + verse_id="arena", + endpoints=(f"cultnet://127.0.0.1:{server.port}",), + roles=("simulation-witness",), + )) + claim_hash = compute_simulation_claim_hash("hit", "alice", "bob", "frame:210") + seen_candidates: list[dict[str, object]] = [] + fanout = CultMeshSimulationObservationFanout( + CultMeshDiscoveryClient("127.0.0.1", server.port, timeout_seconds=2.0), + peers, + verse_id="arena", + roles=["simulation-witness"], + on_candidate=seen_candidates.append, + ) + fanout.enqueue(simulation_observation( + message_id="queued-observation", + witness_runtime_id="python-fanout", + shard_id="arena", + shard_epoch=1, + frame=210, + subject_id="bob", + claim_kind="hit", + claim_hash=claim_hash, + claim_summary="alice hit bob", + ).to_wire()) + + candidates = fanout.flush() + finally: + server.stop() + + self.assertEqual(fanout.pending_count(), 0) + self.assertEqual([candidate["claimHash"] for candidate in candidates], [claim_hash]) + self.assertEqual(seen_candidates[0]["messageId"], "queued-observation") + + def test_cultmesh_simulation_observation_fanout_runs_background_loop(self) -> None: + hub = CultNetSimulationObservationHub( + CultNetSimulationConsensusOptions(minimum_witnesses=1, quorum_ratio=1.0) + ) + server = CultMesh.serve_node(CultMesh.create_node(runtime_id="sim-loop-peer"), observation_hub=hub) + try: + peers = CultMeshPeerCatalog() + peers.upsert(CultMeshPeerCard( + peer_id="sim-loop-peer", + verse_id="arena", + endpoints=(f"cultnet://127.0.0.1:{server.port}",), + roles=("simulation-witness",), + )) + claim_hash = compute_simulation_claim_hash("block", "dana", "eve", "frame:211") + seen_candidates: list[dict[str, object]] = [] + fanout = CultMeshSimulationObservationFanout( + CultMeshDiscoveryClient("127.0.0.1", server.port, timeout_seconds=2.0), + peers, + verse_id="arena", + roles=["simulation-witness"], + interval_seconds=0.05, + on_candidate=seen_candidates.append, + ) + fanout.start() + fanout.enqueue(simulation_observation( + message_id="loop-observation", + witness_runtime_id="python-fanout", + shard_id="arena", + shard_epoch=1, + frame=211, + subject_id="eve", + claim_kind="block", + claim_hash=claim_hash, + claim_summary="dana blocked eve", + ).to_wire()) + deadline = time.monotonic() + 2.0 + while not seen_candidates and time.monotonic() < deadline: + time.sleep(0.01) + fanout.stop() + finally: + server.stop() + + self.assertEqual(fanout.pending_count(), 0) + self.assertTrue(seen_candidates) + self.assertEqual(seen_candidates[0]["claimHash"], claim_hash) + self.assertEqual(seen_candidates[0]["messageId"], "loop-observation") + def test_cultmesh_discovery_client_fans_out_snapshots_to_peers(self) -> None: document = define_database_entry_type( "mesh.snapshot_fanout_note", diff --git a/src/GameCult.Networking/Contracts/cultnet-distributed-database.md b/src/GameCult.Networking/Contracts/cultnet-distributed-database.md index 90955e61..746f1fbb 100644 --- a/src/GameCult.Networking/Contracts/cultnet-distributed-database.md +++ b/src/GameCult.Networking/Contracts/cultnet-distributed-database.md @@ -95,7 +95,8 @@ Not implemented yet: - membership/failure detection - leader election or automatic shard failover - scheduled peer-to-peer snapshot fanout beyond Python's one-shot client helper -- scheduled peer-to-peer fanout for observation gossip and candidate propagation +- cross-runtime scheduled peer-to-peer fanout for observation gossip and + candidate propagation beyond Python's local fanout loop - cross-runtime rollback/resimulation helpers for simulation frames - declared CRDT merge policies @@ -150,8 +151,8 @@ Add discovery fanout and operational polish: Python's local pending-prediction rollback surface - add scheduled peer-to-peer snapshot fanout beyond Python's one-shot client helper -- add scheduled peer-to-peer fanout for observation gossip and candidate - propagation beyond Python's one-shot client helper +- standardize cross-runtime scheduled peer-to-peer fanout for observation gossip + and candidate propagation beyond Python's local fanout loop The log is wire-readable, replicas can apply it explicitly, a pull loop can drive non-primary shards from primary endpoints, and replica cursors can survive