Schedule Python observation fanout

This commit is contained in:
Meta Vens 2026-06-14 13:26:51 +01:00
commit 09ec185355
5 changed files with 180 additions and 8 deletions

View file

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

View file

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

View file

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

View file

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

View file

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