From 25b2022f951906eafce13cb61db52d49233efd0b Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 14 Jun 2026 16:51:30 +0100 Subject: [PATCH] Gate Python simulation observation capabilities --- packages/cultcache-py/PARITY.md | 5 +- .../cultcache-py/src/cultmesh_py/daemon.py | 14 ++- .../cultcache-py/src/cultmesh_py/server.py | 18 +++- packages/cultcache-py/tests/test_cultcache.py | 86 +++++++++++++++++++ 4 files changed, 117 insertions(+), 6 deletions(-) diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index 17394df4..375ad0b7 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -119,7 +119,10 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. notification, and records the mutation in the served shard log. If its durable shard log has been compacted, stale shard-log requests return the same explicit `compacted_history` resync boundary over the daemon wire endpoint - instead of silently looking empty. + instead of silently looking empty. Simulation observation serving is opt-in: + the daemon only advertises `cultnet.simulation_observation.v0` when an + observation hub is attached, and an opt-in launched daemon answers witness + observations with schema-v0 consensus candidates. The daemon CLI snapshot document/byte limits feed the same public server edge; oversized daemon snapshot responses are returned as structured `cultnet.error.v0` peer errors rather than partial payloads. diff --git a/packages/cultcache-py/src/cultmesh_py/daemon.py b/packages/cultcache-py/src/cultmesh_py/daemon.py index 4e738f1e..121fd25d 100644 --- a/packages/cultcache-py/src/cultmesh_py/daemon.py +++ b/packages/cultcache-py/src/cultmesh_py/daemon.py @@ -9,7 +9,7 @@ from pathlib import Path from typing import Any from cultcache_py.interop import INTEROP_SCHEMA_VERSION, interop_note_document -from cultnet_py import hello +from cultnet_py import CultNetSimulationConsensusOptions, CultNetSimulationObservationHub, hello from .facade import CultMesh from .server import CultMeshLocalServer @@ -40,6 +40,9 @@ def main(argv: list[str] | None = None) -> int: parser.add_argument("--seed-interop-note", action="store_true") parser.add_argument("--seed-shard-id", default="interop") parser.add_argument("--seed-shard-epoch", type=int, default=1) + parser.add_argument("--enable-simulation-observations", action="store_true") + parser.add_argument("--simulation-minimum-witnesses", type=int, default=1) + parser.add_argument("--simulation-quorum-ratio", type=float, default=0.5) parser.add_argument("--verse-id") parser.add_argument("--verse-display-name") parser.add_argument("--role", action="append", dest="roles") @@ -87,10 +90,19 @@ def start_server(args: argparse.Namespace) -> CultMeshLocalServer: ) verse_catalog = CultMeshVerseCatalog() peer_catalog = CultMeshPeerCatalog() + observation_hub = None + if args.enable_simulation_observations: + observation_hub = CultNetSimulationObservationHub( + CultNetSimulationConsensusOptions( + minimum_witnesses=args.simulation_minimum_witnesses, + quorum_ratio=args.simulation_quorum_ratio, + ) + ) server = CultMesh.serve_node( node, verse_catalog=verse_catalog, peer_catalog=peer_catalog, + observation_hub=observation_hub, host=args.host, port=args.port, display_name=args.display_name, diff --git a/packages/cultcache-py/src/cultmesh_py/server.py b/packages/cultcache-py/src/cultmesh_py/server.py index cf302baa..17c69713 100644 --- a/packages/cultcache-py/src/cultmesh_py/server.py +++ b/packages/cultcache-py/src/cultmesh_py/server.py @@ -298,11 +298,16 @@ class CultMeshLocalServer: "cultnet.document_delete.v0", "cultnet.shard_catalog_request.v0", "cultnet.shard_log_request.v0", - "cultnet.simulation_observation.v0", - "cultnet.simulation_consensus_candidate.v0", VERSE_CATALOG_REQUEST, PEER_EXCHANGE_REQUEST, - ], + ] + ( + [ + "cultnet.simulation_observation.v0", + "cultnet.simulation_consensus_candidate.v0", + ] + if self.observation_hub is not None + else [] + ), "supportsSchemaCatalog": True, } @@ -357,7 +362,12 @@ class CultMeshLocalServer: def _candidate_responses(self, message: dict[str, Any]) -> list[dict[str, Any]]: if self.observation_hub is None: - return [] + return [self._error_response( + "Simulation observations are not enabled for this CultMesh server.", + message_id=str(message.get("messageId") or ""), + code="simulation_observations_disabled", + details={"schemaVersion": "cultnet.simulation_observation.v0"}, + )] message_id = str(message.get("messageId") or "") return [ { diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index 68539cac..19d051f7 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -3089,6 +3089,7 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(ready["supportedDocumentTypes"], ["cultcache.interop-note"]) self.assertIn("cultnet.hello.v0", ready["supportedMessageVersions"]) self.assertIn("cultnet.document_put_raw.v0", ready["supportedMessageVersions"]) + self.assertNotIn("cultnet.simulation_observation.v0", ready["supportedMessageVersions"]) self.assertEqual(ready["supportedMutationContracts"][0]["documentType"], "cultcache.interop-note") self.assertIn("shardLog", ready["supportedMutationContracts"][0]["operations"]) self.assertEqual(ready["snapshotLimits"], {"maxSnapshotBytes": None, "maxSnapshotDocuments": None}) @@ -3103,6 +3104,7 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(hello_response["displayName"], "Daemon Test Peer") self.assertIn("cultnet.hello.v0", hello_response["supportedMessageVersions"]) self.assertIn("cultnet.schema_catalog_request.v0", hello_response["supportedMessageVersions"]) + self.assertNotIn("cultnet.simulation_observation.v0", hello_response["supportedMessageVersions"]) self.assertEqual(hello_response["supportedDocumentTypes"], ["cultcache.interop-note"]) self.assertEqual(ready["supportedMessageVersions"], hello_response["supportedMessageVersions"]) self.assertEqual(ready["supportedMutationContracts"], hello_response["supportedMutationContracts"]) @@ -3579,6 +3581,90 @@ class CultCacheTests(unittest.TestCase): finally: self._terminate_process(process) + def test_cultmesh_daemon_serves_opt_in_simulation_observations(self) -> None: + with tempfile.TemporaryDirectory() as temp: + ready_path = Path(temp) / "ready.json" + package_src = Path(__file__).resolve().parents[1] / "src" + env = dict(os.environ) + existing_pythonpath = env.get("PYTHONPATH") + env["PYTHONPATH"] = ( + str(package_src) + if not existing_pythonpath + else f"{package_src}{os.pathsep}{existing_pythonpath}" + ) + process = subprocess.Popen( + [ + sys.executable, + "-m", + "cultmesh_py.daemon", + "--runtime-id", + "simulation-daemon-peer", + "--port", + "0", + "--enable-simulation-observations", + "--simulation-minimum-witnesses", + "2", + "--simulation-quorum-ratio", + "1.0", + "--ready-file", + str(ready_path), + ], + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + text=True, + env=env, + ) + try: + ready = self._wait_for_ready_file(process, ready_path) + self.assertIn("cultnet.simulation_observation.v0", ready["supportedMessageVersions"]) + self.assertIn("cultnet.simulation_consensus_candidate.v0", ready["supportedMessageVersions"]) + client = CultMesh.create_client("127.0.0.1", int(ready["port"]), timeout_seconds=2.0) + hello_response = client.request( + hello(runtime_id="simulation-daemon-prober"), + expected_schema_version="cultnet.hello.v0", + ) + self.assertEqual(ready["supportedMessageVersions"], hello_response["supportedMessageVersions"]) + + claim_hash = compute_simulation_claim_hash("hit", "alice", "bob", "frame:100") + first = client.request( + simulation_observation( + message_id="daemon-sim-1", + witness_runtime_id="watcher-1", + shard_id="arena", + shard_epoch=4, + frame=100, + subject_id="bob", + claim_kind="hit", + claim_hash=claim_hash, + claim_summary="alice shot bob first", + ), + expected_schema_version="cultnet.simulation_consensus_candidate.v0", + ) + second = client.request( + simulation_observation( + message_id="daemon-sim-2", + witness_runtime_id="watcher-2", + shard_id="arena", + shard_epoch=4, + frame=100, + subject_id="bob", + claim_kind="hit", + claim_hash=claim_hash, + claim_summary="alice shot bob first", + ), + expected_schema_version="cultnet.simulation_consensus_candidate.v0", + ) + + self.assertEqual(first["messageId"], "daemon-sim-1") + self.assertFalse(first["hasQuorum"]) + self.assertEqual(first["witnessCount"], 1) + self.assertEqual(second["messageId"], "daemon-sim-2") + self.assertTrue(second["hasQuorum"]) + self.assertEqual(second["witnessCount"], 2) + self.assertEqual(second["claimHash"], claim_hash) + finally: + self._terminate_process(process) + def _wait_for_ready_file(self, process: subprocess.Popen[str], ready_path: Path) -> dict[str, object]: deadline = time.monotonic() + 5.0 while not ready_path.exists() and time.monotonic() < deadline: