Gate Python simulation observation capabilities

This commit is contained in:
Meta Vens 2026-06-14 16:51:30 +01:00
commit 25b2022f95
4 changed files with 117 additions and 6 deletions

View file

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

View file

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

View file

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

View file

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