diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index ce2a68ef..76d20bd5 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -227,11 +227,11 @@ Current receipts: CultCache v1 parity matrix with TypeScript, Rust, and C#. - `packages/cultnet-ts/test/interop/cultnet-interop.test.ts` includes Python in the live TS/Rust/C#/Python schema-v0 peer ring: discovery, hello, schema - catalog, raw snapshot, raw document put/delete, mutation receipt, - fire-command receipt, database subscription changes, shard catalog, shard log - catch-up, simulation consensus candidates, and witness artifact bundle - round-trips. The same test asks the Python peer for CultMesh Verse catalog and - peer exchange responses over the CultNet pipe. + catalog, wire-message catalog discovery, raw snapshot, raw document + put/delete, mutation receipt, fire-command receipt, database subscription + changes, shard catalog, shard log catch-up, simulation consensus candidates, + and witness artifact bundle round-trips. The same test asks the Python peer + for CultMesh Verse catalog and peer exchange responses over the CultNet pipe. - `packages/cultcache-py/tests/test_cultcache.py` covers Python CultMesh Verse catalog, peer exchange, authority lease, stream negotiation, CultNet helper shapes, simulation claim hashing, and witness artifact bundle payload diff --git a/packages/cultcache-py/src/cultnet_py/interop_peer.py b/packages/cultcache-py/src/cultnet_py/interop_peer.py index 4b46caa4..d46550b5 100644 --- a/packages/cultcache-py/src/cultnet_py/interop_peer.py +++ b/packages/cultcache-py/src/cultnet_py/interop_peer.py @@ -2,6 +2,7 @@ from __future__ import annotations import argparse from collections import defaultdict +import hashlib import json import selectors import signal @@ -56,6 +57,30 @@ WITNESS_ARTIFACT_BUNDLE_SCHEMA_VERSION = "cultnet.witness_artifact_bundle.v0" INTEROP_WIRE_CONTRACT = "cultnet.schema.v0" DISCOVERY_PROBE_SCHEMA_VERSION = "cultnet.discovery_probe.v0" DISCOVERY_ANNOUNCE_SCHEMA_VERSION = "cultnet.discovery_announce.v0" +CULTNET_SCHEMA_BASE = "https://github.com/GameCult/cultnet-ts/contracts" + +WIRE_MESSAGE_SCHEMA_VERSIONS = ( + ("cultnet.hello.v0", "CultNet Hello Message", f"{CULTNET_SCHEMA_BASE}/cultnet.hello.schema.json"), + ("cultnet.document_delete.v0", "CultNet Document Delete Message", f"{CULTNET_SCHEMA_BASE}/cultnet.document-delete.schema.json"), + ("cultnet.document_put_raw.v0", "CultNet Raw Document Put Message", f"{CULTNET_SCHEMA_BASE}/cultnet.document-put-raw.schema.json"), + ("cultnet.snapshot_request.v0", "CultNet Snapshot Request Message", f"{CULTNET_SCHEMA_BASE}/cultnet.snapshot-request.schema.json"), + ("cultnet.snapshot_response_raw.v0", "CultNet Raw Snapshot Response Message", f"{CULTNET_SCHEMA_BASE}/cultnet.snapshot-response-raw.schema.json"), + ("cultnet.schema_catalog_request.v0", "CultNet Schema Catalog Request Message", f"{CULTNET_SCHEMA_BASE}/cultnet.schema-catalog-request.schema.json"), + ("cultnet.schema_catalog_response.v0", "CultNet Schema Catalog Response Message", f"{CULTNET_SCHEMA_BASE}/cultnet.schema-catalog-response.schema.json"), + ("cultnet.database_subscribe.v0", "CultNet Database Subscribe Message", f"{CULTNET_SCHEMA_BASE}/cultnet.database-subscribe.schema.json"), + ("cultnet.database_unsubscribe.v0", "CultNet Database Unsubscribe Message", f"{CULTNET_SCHEMA_BASE}/cultnet.database-unsubscribe.schema.json"), + ("cultnet.database_change_raw.v0", "CultNet Raw Database Change Message", f"{CULTNET_SCHEMA_BASE}/cultnet.database-change-raw.schema.json"), + ("cultnet.shard_catalog_request.v0", "CultNet Shard Catalog Request Message", f"{CULTNET_SCHEMA_BASE}/cultnet.shard-catalog-request.schema.json"), + ("cultnet.shard_catalog_response.v0", "CultNet Shard Catalog Response Message", f"{CULTNET_SCHEMA_BASE}/cultnet.shard-catalog-response.schema.json"), + ("cultnet.shard_log_request.v0", "CultNet Shard Log Request Message", f"{CULTNET_SCHEMA_BASE}/cultnet.shard-log-request.schema.json"), + ("cultnet.shard_log_response.v0", "CultNet Shard Log Response Message", f"{CULTNET_SCHEMA_BASE}/cultnet.shard-log-response.schema.json"), + ("cultnet.simulation_observation.v0", "CultNet Simulation Observation Message", f"{CULTNET_SCHEMA_BASE}/cultnet.simulation-observation.schema.json"), + ("cultnet.simulation_consensus_candidate.v0", "CultNet Simulation Consensus Candidate Message", f"{CULTNET_SCHEMA_BASE}/cultnet.simulation-consensus-candidate.schema.json"), + (VERSE_CATALOG_REQUEST, "CultMesh Verse Catalog Request Message", f"{CULTNET_SCHEMA_BASE}/cultmesh.verse-catalog-request.schema.json"), + ("cultmesh.verse_catalog_response.v0", "CultMesh Verse Catalog Response Message", f"{CULTNET_SCHEMA_BASE}/cultmesh.verse-catalog-response.schema.json"), + (PEER_EXCHANGE_REQUEST, "CultMesh Peer Exchange Request Message", f"{CULTNET_SCHEMA_BASE}/cultmesh.peer-exchange-request.schema.json"), + ("cultmesh.peer_exchange_response.v0", "CultMesh Peer Exchange Response Message", f"{CULTNET_SCHEMA_BASE}/cultmesh.peer-exchange-response.schema.json"), +) @dataclass(frozen=True) @@ -793,6 +818,12 @@ def catalog_response(state: PeerState, request: dict[str, Any]) -> dict[str, Any kinds = set(request.get("kinds") or []) include_schema_json = request.get("includeSchemaJson") is True schemas = [] + for descriptor in wire_message_schema_descriptors(include_schema_json): + if schema_ids and descriptor["schemaId"] not in schema_ids: + continue + if kinds and descriptor["kind"] not in kinds: + continue + schemas.append(descriptor) if (not schema_ids or state.note_schema_id in schema_ids) and (not kinds or "document_payload" in kinds): schemas.append({ "schemaId": state.note_schema_id, @@ -818,6 +849,37 @@ def catalog_response(state: PeerState, request: dict[str, Any]) -> dict[str, Any return {"schemaVersion": "cultnet.schema_catalog_response.v0", "messageId": request.get("messageId", ""), "schemas": schemas} +def wire_message_schema_descriptors(include_schema_json: bool) -> list[dict[str, Any]]: + descriptors = [] + for schema_version, title, schema_id in WIRE_MESSAGE_SCHEMA_VERSIONS: + schema_json = wire_message_schema_json(schema_id, title, schema_version) + descriptor: dict[str, Any] = { + "schemaId": schema_id, + "kind": "wire_message", + "schemaVersion": schema_version, + "title": title, + "wireContracts": [INTEROP_WIRE_CONTRACT], + "contentHash": hashlib.sha256(schema_json.encode("utf-8")).hexdigest(), + } + if include_schema_json: + descriptor["schemaJson"] = schema_json + descriptors.append(descriptor) + return descriptors + + +def wire_message_schema_json(schema_id: str, title: str, schema_version: str) -> str: + return json.dumps({ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": schema_id, + "title": title, + "type": "object", + "required": ["schemaVersion"], + "properties": { + "schemaVersion": {"const": schema_version}, + }, + }, separators=(",", ":"), sort_keys=True) + + def raw_snapshot_response(state: PeerState, request: dict[str, Any]) -> dict[str, Any]: schema_ids = set(request.get("schemaIds") or []) record_keys = set(request.get("recordKeys") or []) diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index ca3d3cbe..4f642e26 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -15,6 +15,7 @@ from cultcache_py import ( ) from cultcache_py.interop import read_note, write_note from cultnet_py import compute_simulation_claim_hash, database_subscribe, database_unsubscribe, decode_frame, decode_witness_artifact_bundle_payload, document_delete, document_put_raw, encode_frame, encode_witness_artifact_bundle_payload, hello, parse_message, shard_catalog_request, shard_log_request, simulation_observation, witness_artifact_bundle +from cultnet_py.interop_peer import wire_message_schema_descriptors from cultmesh_py import create_node from cultmesh_py import ( CultMeshPeerCard, @@ -222,6 +223,22 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(message["shardId"], "interop") self.assertEqual(message["shardEpoch"], 1) + def test_cultnet_wire_catalog_describes_python_handled_messages(self) -> None: + descriptors = wire_message_schema_descriptors(include_schema_json=True) + by_version = {descriptor["schemaVersion"]: descriptor for descriptor in descriptors} + for schema_version in [ + "cultnet.document_delete.v0", + "cultnet.database_change_raw.v0", + "cultnet.shard_log_response.v0", + "cultnet.simulation_consensus_candidate.v0", + "cultmesh.peer_exchange_response.v0", + ]: + self.assertIn(schema_version, by_version) + self.assertEqual(by_version[schema_version]["kind"], "wire_message") + self.assertIn("cultnet.schema.v0", by_version[schema_version]["wireContracts"]) + self.assertIn(schema_version, by_version[schema_version]["schemaJson"]) + self.assertEqual(len(by_version[schema_version]["contentHash"]), 64) + def test_cultnet_shard_helpers_match_schema_v0_shape(self) -> None: catalog = shard_catalog_request( message_id="catalog-1", diff --git a/packages/cultnet-ts/test/interop/cultnet-interop.test.ts b/packages/cultnet-ts/test/interop/cultnet-interop.test.ts index 2ab2fb71..9759e31e 100644 --- a/packages/cultnet-ts/test/interop/cultnet-interop.test.ts +++ b/packages/cultnet-ts/test/interop/cultnet-interop.test.ts @@ -244,6 +244,29 @@ test("CultNet TS/Rust/C#/Python peers discover each other and exchange raw state assert.ok(tsDialPython.mutatedNote.tags.includes("decorated:ts-python-client")); assert.equal(tsDialPython.fireReceipt.ammoRemaining, 29); + const pythonWireCatalog = await requestCultMeshFromPython(pythonPort, { + schemaVersion: "cultnet.schema_catalog_request.v0", + messageId: "python-wire-catalog", + includeSchemaJson: true, + kinds: ["wire_message"], + }); + assert.equal(pythonWireCatalog.schemaVersion, "cultnet.schema_catalog_response.v0"); + assert.equal(pythonWireCatalog.messageId, "python-wire-catalog"); + const pythonWireVersions = new Set(pythonWireCatalog.schemas.map((schema: any) => schema.schemaVersion)); + for (const schemaVersion of [ + "cultnet.document_delete.v0", + "cultnet.database_change_raw.v0", + "cultnet.shard_log_response.v0", + "cultnet.simulation_consensus_candidate.v0", + "cultmesh.peer_exchange_response.v0", + ]) { + assert.ok(pythonWireVersions.has(schemaVersion), `Python wire catalog should include ${schemaVersion}`); + } + const pythonDeleteDescriptor = pythonWireCatalog.schemas.find((schema: any) => schema.schemaVersion === "cultnet.document_delete.v0"); + assert.equal(pythonDeleteDescriptor.kind, "wire_message"); + assert.ok(pythonDeleteDescriptor.wireContracts.includes("cultnet.schema.v0")); + assert.ok(String(pythonDeleteDescriptor.schemaJson).includes("cultnet.document_delete.v0")); + const pythonVerseCatalog = await requestCultMeshFromPython(pythonPort, { schemaVersion: "cultmesh.verse_catalog_request.v0", messageId: "python-verses",