Add Python CultNet schema catalog facade

This commit is contained in:
Meta Vens 2026-06-14 03:51:50 +01:00
commit c47b84560e
6 changed files with 217 additions and 2 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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