diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index 25d489f8..ef67875a 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -17,7 +17,10 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. - Python CultNet schema catalog: Exposes shared wire-message schema descriptors from the package surface so both the interop peer and CultMesh local server describe the CultNet/CultMesh - messages they speak through the same catalog authority. + messages they speak through the same catalog authority. Python callers can + also ingest and filter remote schema catalog responses through typed + `CultNetSchemaCatalog` and `CultNetSchemaDescriptor` helpers, including + `CultNetRawClient.sync_schema_catalog(...)`. - Python CultMesh discovery client: Fetches Verse catalogs and peer exchange responses from the live Python endpoint over CultNet frames. diff --git a/packages/cultcache-py/src/cultcache_py/verify.py b/packages/cultcache-py/src/cultcache_py/verify.py index f09df2c3..371f1124 100644 --- a/packages/cultcache-py/src/cultcache_py/verify.py +++ b/packages/cultcache-py/src/cultcache_py/verify.py @@ -32,6 +32,8 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = { "CultNetDatabaseSubscription", "CultNetMessage", "CultNetRawClient", + "CultNetSchemaCatalog", + "CultNetSchemaDescriptor", "CultNetSimulationConsensus", "CultNetSimulationConsensusOptions", "CultNetSimulationObservationHub", @@ -58,6 +60,7 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = { "simulation_observation", "snapshot_request", "wire_message_schema_descriptors", + "wire_message_schema_catalog", "wire_message_schema_json", "witness_artifact_bundle", "write_frame", diff --git a/packages/cultcache-py/src/cultnet_py/__init__.py b/packages/cultcache-py/src/cultnet_py/__init__.py index e0a3b2a7..be16cc72 100644 --- a/packages/cultcache-py/src/cultnet_py/__init__.py +++ b/packages/cultcache-py/src/cultnet_py/__init__.py @@ -27,8 +27,11 @@ from .replication import ( schema_document_map, ) from .schema_catalog import ( + CultNetSchemaCatalog, + CultNetSchemaDescriptor, INTEROP_WIRE_CONTRACT, wire_message_schema_descriptors, + wire_message_schema_catalog, wire_message_schema_json, ) from .simulation import ( @@ -41,6 +44,8 @@ __all__ = [ "CultNetMessage", "CultNetDatabaseSubscription", "CultNetRawClient", + "CultNetSchemaCatalog", + "CultNetSchemaDescriptor", "CultNetAppliedRecord", "CultNetClientAuthorityScope", "CultNetSimulationConsensus", @@ -69,6 +74,7 @@ __all__ = [ "simulation_observation", "snapshot_request", "wire_message_schema_descriptors", + "wire_message_schema_catalog", "wire_message_schema_json", "witness_artifact_bundle", "write_frame", diff --git a/packages/cultcache-py/src/cultnet_py/client.py b/packages/cultcache-py/src/cultnet_py/client.py index 9bb59d94..633e22f0 100644 --- a/packages/cultcache-py/src/cultnet_py/client.py +++ b/packages/cultcache-py/src/cultnet_py/client.py @@ -16,6 +16,7 @@ from .messages import ( shard_log_request, snapshot_request, ) +from .schema_catalog import CultNetSchemaCatalog, CultNetSchemaDescriptor @dataclass(frozen=True) @@ -57,6 +58,39 @@ class CultNetRawClient: expected_schema_version="cultnet.schema_catalog_response.v0", ) + def fetch_schema_descriptors( + self, + *, + message_id: str = "cultnet-python-schema-catalog", + include_schema_json: bool = False, + schema_ids: list[str] | None = None, + kinds: list[str] | None = None, + ) -> list[CultNetSchemaDescriptor]: + response = self.fetch_schema_catalog( + message_id=message_id, + include_schema_json=include_schema_json, + schema_ids=schema_ids, + kinds=kinds, + ) + return CultNetSchemaCatalog().apply_response(response) + + def sync_schema_catalog( + self, + catalog: CultNetSchemaCatalog, + *, + message_id: str = "cultnet-python-schema-catalog", + include_schema_json: bool = False, + schema_ids: list[str] | None = None, + kinds: list[str] | None = None, + ) -> list[CultNetSchemaDescriptor]: + response = self.fetch_schema_catalog( + message_id=message_id, + include_schema_json=include_schema_json, + schema_ids=schema_ids, + kinds=kinds, + ) + return catalog.apply_response(response) + def fetch_snapshot( self, *, diff --git a/packages/cultcache-py/src/cultnet_py/schema_catalog.py b/packages/cultcache-py/src/cultnet_py/schema_catalog.py index ad360e2a..f09fcb21 100644 --- a/packages/cultcache-py/src/cultnet_py/schema_catalog.py +++ b/packages/cultcache-py/src/cultnet_py/schema_catalog.py @@ -2,6 +2,7 @@ from __future__ import annotations import hashlib import json +from dataclasses import dataclass, field from typing import Any INTEROP_WIRE_CONTRACT = "cultnet.schema.v0" @@ -33,6 +34,110 @@ WIRE_MESSAGE_SCHEMA_VERSIONS = ( ) +@dataclass(frozen=True) +class CultNetSchemaDescriptor: + schema_id: str + kind: str + schema_version: str | None = None + document_type: str | None = None + title: str | None = None + wire_contracts: tuple[str, ...] = () + content_hash: str | None = None + schema_json: str | None = None + + @classmethod + def from_wire(cls, value: dict[str, Any]) -> "CultNetSchemaDescriptor": + schema_id = str(value.get("schemaId") or "") + kind = str(value.get("kind") or "") + if not schema_id: + raise ValueError("schema descriptor schemaId must be non-empty") + if not kind: + raise ValueError("schema descriptor kind must be non-empty") + return cls( + schema_id=schema_id, + kind=kind, + schema_version=_optional_string(value.get("schemaVersion")), + document_type=_optional_string(value.get("documentType")), + title=_optional_string(value.get("title")), + wire_contracts=tuple(str(contract) for contract in value.get("wireContracts") or []), + content_hash=_optional_string(value.get("contentHash")), + schema_json=_optional_string(value.get("schemaJson")), + ) + + def to_wire(self, *, include_schema_json: bool | None = None) -> dict[str, Any]: + wire: dict[str, Any] = { + "schemaId": self.schema_id, + "kind": self.kind, + "wireContracts": list(self.wire_contracts), + } + if self.schema_version is not None: + wire["schemaVersion"] = self.schema_version + if self.document_type is not None: + wire["documentType"] = self.document_type + if self.title is not None: + wire["title"] = self.title + if self.content_hash is not None: + wire["contentHash"] = self.content_hash + if self.schema_json is not None and include_schema_json is not False: + wire["schemaJson"] = self.schema_json + return wire + + +@dataclass +class CultNetSchemaCatalog: + _descriptors: dict[str, CultNetSchemaDescriptor] = field(default_factory=dict) + + def upsert(self, descriptor: CultNetSchemaDescriptor | dict[str, Any]) -> CultNetSchemaDescriptor: + value = descriptor if isinstance(descriptor, CultNetSchemaDescriptor) else CultNetSchemaDescriptor.from_wire(descriptor) + self._descriptors[value.schema_id] = value + return value + + def get(self, schema_id: str) -> CultNetSchemaDescriptor | None: + return self._descriptors.get(schema_id) + + def list( + self, + *, + schema_ids: list[str] | None = None, + kinds: list[str] | None = None, + ) -> list[CultNetSchemaDescriptor]: + requested_schema_ids = set(schema_ids or []) + requested_kinds = set(kinds or []) + return [ + descriptor + for descriptor in sorted(self._descriptors.values(), key=lambda item: item.schema_id) + if (not requested_schema_ids or descriptor.schema_id in requested_schema_ids) + and (not requested_kinds or descriptor.kind in requested_kinds) + ] + + def apply_response(self, response: dict[str, Any]) -> list[CultNetSchemaDescriptor]: + if response.get("schemaVersion") != "cultnet.schema_catalog_response.v0": + raise ValueError(f"Expected cultnet.schema_catalog_response.v0, received {response.get('schemaVersion')!r}") + applied = [] + for descriptor in response.get("schemas") or []: + if not isinstance(descriptor, dict): + continue + applied.append(self.upsert(descriptor)) + return applied + + def create_response( + self, + *, + message_id: str = "", + include_schema_json: bool = False, + schema_ids: list[str] | None = None, + kinds: list[str] | None = None, + ) -> dict[str, Any]: + return { + "schemaVersion": "cultnet.schema_catalog_response.v0", + "messageId": message_id, + "schemas": [ + descriptor.to_wire(include_schema_json=include_schema_json) + for descriptor in self.list(schema_ids=schema_ids, kinds=kinds) + ], + } + + 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: @@ -51,6 +156,13 @@ def wire_message_schema_descriptors(include_schema_json: bool) -> list[dict[str, return descriptors +def wire_message_schema_catalog(*, include_schema_json: bool = True) -> CultNetSchemaCatalog: + catalog = CultNetSchemaCatalog() + for descriptor in wire_message_schema_descriptors(include_schema_json): + catalog.upsert(descriptor) + return catalog + + def wire_message_schema_json(schema_id: str, title: str, schema_version: str) -> str: properties = { "schemaVersion": {"const": schema_version}, @@ -296,3 +408,10 @@ def wire_message_shared_defs() -> dict[str, Any]: "verseDescriptor": {"type": "object"}, "peerCard": {"type": "object"}, } + + +def _optional_string(value: Any) -> str | None: + if value is None: + return None + text = str(value) + return text if text else None diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index 66684b32..2c1335dd 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -24,6 +24,8 @@ from cultnet_py import ( compute_simulation_claim_hash, CultNetClientAuthorityScope, CultNetRawClient, + CultNetSchemaCatalog, + CultNetSchemaDescriptor, CultNetSimulationConsensusOptions, apply_raw_snapshot, apply_shard_log_response, @@ -42,9 +44,10 @@ from cultnet_py import ( shard_log_request, simulation_observation, snapshot_request, + wire_message_schema_catalog, + wire_message_schema_descriptors, witness_artifact_bundle, ) -from cultnet_py import wire_message_schema_descriptors from cultmesh_py import create_node from cultmesh_py import ( CultMesh, @@ -835,6 +838,45 @@ class CultCacheTests(unittest.TestCase): for required_field in ["witnessCount", "supportWeight", "totalWeight", "hasQuorum", "confidence"]: self.assertIn(required_field, consensus_schema["required"]) + def test_cultnet_schema_catalog_applies_filters_and_responses(self) -> None: + catalog = wire_message_schema_catalog(include_schema_json=True) + descriptor = catalog.get("https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json") + self.assertIsNotNone(descriptor) + assert descriptor is not None + self.assertEqual(descriptor.kind, "wire_message") + self.assertEqual(descriptor.schema_version, "cultnet.document_put_raw.v0") + self.assertIsNotNone(descriptor.schema_json) + + filtered = catalog.list(kinds=["wire_message"], schema_ids=[descriptor.schema_id]) + self.assertEqual(filtered, [descriptor]) + + response = catalog.create_response( + message_id="catalog-response", + include_schema_json=False, + schema_ids=[descriptor.schema_id], + kinds=["wire_message"], + ) + self.assertEqual(response["schemaVersion"], "cultnet.schema_catalog_response.v0") + self.assertNotIn("schemaJson", response["schemas"][0]) + + remote = CultNetSchemaCatalog() + applied = remote.apply_response({ + "schemaVersion": "cultnet.schema_catalog_response.v0", + "messageId": "remote", + "schemas": [ + CultNetSchemaDescriptor( + schema_id="schema:custom", + kind="shared_contract", + schema_version="custom.v0", + wire_contracts=("cultnet.schema.v0",), + content_hash="hash", + schema_json="{}", + ).to_wire() + ], + }) + self.assertEqual(applied[0].schema_id, "schema:custom") + self.assertEqual(remote.get("schema:custom"), applied[0]) + def test_cultnet_shard_helpers_match_schema_v0_shape(self) -> None: catalog = shard_catalog_request( message_id="catalog-1", @@ -1658,6 +1700,12 @@ class CultCacheTests(unittest.TestCase): hello_response = raw_client.request(hello(runtime_id="probe"), expected_schema_version="cultnet.hello.v0") schema_response = raw_client.fetch_schema_catalog(schema_ids=["mesh.server_note.v1"], include_schema_json=True) wire_schema_response = raw_client.fetch_schema_catalog(kinds=["wire_message"], include_schema_json=True) + synced_schema_catalog = CultNetSchemaCatalog() + synced_wire_descriptors = raw_client.sync_schema_catalog( + synced_schema_catalog, + kinds=["wire_message"], + include_schema_json=True, + ) snapshot_response = raw_client.fetch_snapshot(schema_ids=["mesh.server_note.v1"]) shard_catalog = raw_client.fetch_shard_catalog(schema_ids=["mesh.server_note.v1"]) shard_log = raw_client.fetch_shard_log(shard_id="primary", shard_epoch=1) @@ -1697,6 +1745,8 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(wire_descriptors["cultnet.document_put_raw.v0"]["kind"], "wire_message") self.assertIn("schemaJson", wire_descriptors["cultnet.document_put_raw.v0"]) self.assertIn("cultmesh.peer_exchange_response.v0", wire_descriptors) + self.assertIn("cultnet.document_put_raw.v0", {descriptor.schema_version for descriptor in synced_wire_descriptors}) + self.assertIsNotNone(synced_schema_catalog.get("https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json")) self.assertEqual(snapshot_response["documents"][0]["recordKey"], "note:1") self.assertEqual(shard_catalog["shards"][0]["schemaIds"], ["mesh.server_note.v1"]) self.assertEqual(shard_log["entries"][0]["changeKind"], "added")