Publish Python wire schema catalog

This commit is contained in:
Meta Vens 2026-06-13 22:49:56 +01:00
commit 9d69445e47
4 changed files with 107 additions and 5 deletions

View file

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

View file

@ -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 [])

View file

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

View file

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