diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index 33b45bf0..f9b10834 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -14,6 +14,10 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. - Python CultNet raw client: Fetches schema catalogs, raw snapshots, shard catalogs, shard logs, and live database subscription changes. +- Python CultNet raw snapshot: + Provides typed `CultNetRawSnapshotResponse` and `CultNetRawDocumentRecord` + helpers plus `CultNetRawClient.fetch_snapshot_response(...)` for inspecting + peer snapshots before handing them to the existing replication helpers. - 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 diff --git a/packages/cultcache-py/src/cultcache_py/verify.py b/packages/cultcache-py/src/cultcache_py/verify.py index daf410ac..1544bc84 100644 --- a/packages/cultcache-py/src/cultcache_py/verify.py +++ b/packages/cultcache-py/src/cultcache_py/verify.py @@ -33,6 +33,8 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = { "CultNetDatabaseSubscription", "CultNetMessage", "CultNetRawClient", + "CultNetRawDocumentRecord", + "CultNetRawSnapshotResponse", "CultNetSchemaCatalog", "CultNetSchemaDescriptor", "CultNetShardCatalog", diff --git a/packages/cultcache-py/src/cultnet_py/__init__.py b/packages/cultcache-py/src/cultnet_py/__init__.py index 34283849..b89c961b 100644 --- a/packages/cultcache-py/src/cultnet_py/__init__.py +++ b/packages/cultcache-py/src/cultnet_py/__init__.py @@ -36,6 +36,7 @@ from .schema_catalog import ( ) from .shard_catalog import CultNetShardCatalog, CultNetShardDescriptor from .shard_log import CultNetShardLogEntry, CultNetShardLogResponse +from .snapshot import CultNetRawDocumentRecord, CultNetRawSnapshotResponse from .subscription import CultNetDatabaseChange from .simulation import ( CultNetSimulationConsensus, @@ -54,6 +55,8 @@ __all__ = [ "CultNetShardDescriptor", "CultNetShardLogEntry", "CultNetShardLogResponse", + "CultNetRawDocumentRecord", + "CultNetRawSnapshotResponse", "CultNetAppliedRecord", "CultNetClientAuthorityScope", "CultNetSimulationConsensus", diff --git a/packages/cultcache-py/src/cultnet_py/client.py b/packages/cultcache-py/src/cultnet_py/client.py index 092266c6..d05e188e 100644 --- a/packages/cultcache-py/src/cultnet_py/client.py +++ b/packages/cultcache-py/src/cultnet_py/client.py @@ -19,6 +19,7 @@ from .messages import ( from .schema_catalog import CultNetSchemaCatalog, CultNetSchemaDescriptor from .shard_catalog import CultNetShardCatalog, CultNetShardDescriptor from .shard_log import CultNetShardLogResponse +from .snapshot import CultNetRawSnapshotResponse from .subscription import CultNetDatabaseChange @@ -114,6 +115,23 @@ class CultNetRawClient: expected_schema_version="cultnet.snapshot_response_raw.v0", ) + def fetch_snapshot_response( + self, + *, + message_id: str = "cultnet-python-snapshot", + schema_ids: list[str] | None = None, + record_keys: list[str] | None = None, + shard_id: str | None = None, + shard_epoch: int | None = None, + ) -> CultNetRawSnapshotResponse: + return CultNetRawSnapshotResponse.from_wire(self.fetch_snapshot( + message_id=message_id, + schema_ids=schema_ids, + record_keys=record_keys, + shard_id=shard_id, + shard_epoch=shard_epoch, + )) + def fetch_shard_catalog( self, *, diff --git a/packages/cultcache-py/src/cultnet_py/snapshot.py b/packages/cultcache-py/src/cultnet_py/snapshot.py new file mode 100644 index 00000000..f529ca92 --- /dev/null +++ b/packages/cultcache-py/src/cultnet_py/snapshot.py @@ -0,0 +1,123 @@ +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + + +@dataclass(frozen=True) +class CultNetRawDocumentRecord: + schema_id: str + record_key: str + payload: bytes + stored_at: str | None = None + payload_encoding: str = "messagepack" + source_runtime_id: str | None = None + source_agent_id: str | None = None + source_role: str | None = None + tags: tuple[str, ...] = () + + @classmethod + def from_wire(cls, value: dict[str, Any]) -> "CultNetRawDocumentRecord": + schema_id = str(value.get("schemaId") or "") + record_key = str(value.get("recordKey") or "") + if not schema_id: + raise ValueError("raw document record schemaId must be non-empty") + if not record_key: + raise ValueError("raw document record recordKey must be non-empty") + return cls( + schema_id=schema_id, + record_key=record_key, + payload=bytes(value.get("payload") or b""), + stored_at=_optional_string(value.get("storedAt")), + payload_encoding=str(value.get("payloadEncoding") or "messagepack"), + source_runtime_id=_optional_string(value.get("sourceRuntimeId")), + source_agent_id=_optional_string(value.get("sourceAgentId")), + source_role=_optional_string(value.get("sourceRole")), + tags=tuple(str(tag) for tag in value.get("tags") or ()), + ) + + def to_wire(self) -> dict[str, Any]: + wire: dict[str, Any] = { + "schemaId": self.schema_id, + "recordKey": self.record_key, + "payloadEncoding": self.payload_encoding, + "payload": self.payload, + } + if self.stored_at is not None: + wire["storedAt"] = self.stored_at + if self.source_runtime_id is not None: + wire["sourceRuntimeId"] = self.source_runtime_id + if self.source_agent_id is not None: + wire["sourceAgentId"] = self.source_agent_id + if self.source_role is not None: + wire["sourceRole"] = self.source_role + if self.tags: + wire["tags"] = list(self.tags) + return wire + + +@dataclass(frozen=True) +class CultNetRawSnapshotResponse: + message_id: str + documents: tuple[CultNetRawDocumentRecord, ...] + shard_id: str | None = None + shard_epoch: int | None = None + shard_log_sequence: int | None = None + + @classmethod + def from_wire(cls, response: dict[str, Any]) -> "CultNetRawSnapshotResponse": + if response.get("schemaVersion") != "cultnet.snapshot_response_raw.v0": + raise ValueError(f"Expected cultnet.snapshot_response_raw.v0, received {response.get('schemaVersion')!r}") + return cls( + message_id=str(response.get("messageId") or ""), + documents=tuple( + CultNetRawDocumentRecord.from_wire(document) + for document in response.get("documents") or () + if isinstance(document, dict) + ), + shard_id=_optional_string(response.get("shardId")), + shard_epoch=_optional_int(response.get("shardEpoch")), + shard_log_sequence=_optional_int(response.get("shardLogSequence")), + ) + + def filter( + self, + *, + schema_ids: list[str] | None = None, + record_keys: list[str] | None = None, + ) -> tuple[CultNetRawDocumentRecord, ...]: + requested_schema_ids = set(schema_ids or []) + requested_record_keys = set(record_keys or []) + return tuple( + document + for document in self.documents + if (not requested_schema_ids or document.schema_id in requested_schema_ids) + and (not requested_record_keys or document.record_key in requested_record_keys) + ) + + def to_wire(self) -> dict[str, Any]: + wire: dict[str, Any] = { + "schemaVersion": "cultnet.snapshot_response_raw.v0", + "messageId": self.message_id, + "documents": [document.to_wire() for document in self.documents], + } + if self.shard_id is not None: + wire["shardId"] = self.shard_id + if self.shard_epoch is not None: + wire["shardEpoch"] = self.shard_epoch + if self.shard_log_sequence is not None: + wire["shardLogSequence"] = self.shard_log_sequence + return wire + + +def _optional_string(value: Any) -> str | None: + if value is None: + return None + text = str(value) + return text if text else None + + +def _optional_int(value: Any) -> int | None: + if value is None: + return None + return int(value) diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index bb3282a3..3b97da0c 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -25,6 +25,8 @@ from cultnet_py import ( CultNetDatabaseChange, CultNetClientAuthorityScope, CultNetRawClient, + CultNetRawDocumentRecord, + CultNetRawSnapshotResponse, CultNetSchemaCatalog, CultNetSchemaDescriptor, CultNetShardCatalog, @@ -429,6 +431,38 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(snapshot["shardId"], "interop") self.assertEqual(snapshot["shardEpoch"], 1) + def test_cultnet_raw_snapshot_response_filters_and_roundtrips_records(self) -> None: + response = CultNetRawSnapshotResponse.from_wire({ + "schemaVersion": "cultnet.snapshot_response_raw.v0", + "messageId": "snapshot-1", + "shardId": "notes", + "shardEpoch": 3, + "shardLogSequence": 8, + "documents": [ + CultNetRawDocumentRecord( + schema_id="schema-note", + record_key="note:1", + stored_at="2026-06-14T00:00:00Z", + payload=b"note", + source_runtime_id="python-test", + tags=("snapshot",), + ).to_wire(), + { + "schemaId": "schema-fact", + "recordKey": "fact:1", + "payloadEncoding": "messagepack", + "payload": b"fact", + }, + ], + }) + self.assertEqual(response.shard_id, "notes") + self.assertEqual(response.shard_epoch, 3) + self.assertEqual(response.shard_log_sequence, 8) + self.assertEqual(response.documents[0].source_runtime_id, "python-test") + self.assertEqual(response.filter(schema_ids=["schema-note"])[0].record_key, "note:1") + self.assertEqual(response.filter(record_keys=["fact:1"])[0].schema_id, "schema-fact") + self.assertEqual(response.to_wire()["documents"][0]["tags"], ["snapshot"]) + def test_cultnet_raw_client_fetches_schema_snapshot_and_shard_reads(self) -> None: import msgpack # type: ignore from cultnet_py import read_frame, write_frame @@ -496,7 +530,9 @@ class CultCacheTests(unittest.TestCase): client = CultNetRawClient("127.0.0.1", port_holder[0], timeout_seconds=2.0) self.assertEqual(client.fetch_schema_catalog(kinds=["wire_message"])["schemaVersion"], "cultnet.schema_catalog_response.v0") - self.assertEqual(client.fetch_snapshot(shard_id="interop", shard_epoch=1)["schemaVersion"], "cultnet.snapshot_response_raw.v0") + typed_snapshot = client.fetch_snapshot_response(shard_id="interop", shard_epoch=1) + self.assertEqual(typed_snapshot.shard_id, None) + self.assertEqual(typed_snapshot.documents, ()) shard_catalog = CultNetShardCatalog() synced_shards = client.sync_shard_catalog(shard_catalog, schema_ids=["schema-a"]) self.assertEqual(synced_shards[0].shard_id, "interop") @@ -1835,6 +1871,7 @@ class CultCacheTests(unittest.TestCase): include_schema_json=True, ) snapshot_response = raw_client.fetch_snapshot(schema_ids=["mesh.server_note.v1"]) + typed_snapshot_response = raw_client.fetch_snapshot_response(schema_ids=["mesh.server_note.v1"]) shard_catalog = raw_client.fetch_shard_catalog(schema_ids=["mesh.server_note.v1"]) synced_shard_catalog = CultNetShardCatalog() synced_shards = raw_client.sync_shard_catalog(synced_shard_catalog, schema_ids=["mesh.server_note.v1"]) @@ -1879,6 +1916,8 @@ class CultCacheTests(unittest.TestCase): 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(typed_snapshot_response.documents[0].record_key, "note:1") + self.assertEqual(typed_snapshot_response.documents[0].schema_id, "mesh.server_note.v1") self.assertEqual(shard_catalog["shards"][0]["schemaIds"], ["mesh.server_note.v1"]) self.assertEqual(synced_shards[0].shard_id, "primary") self.assertEqual(synced_shard_catalog.get("primary"), synced_shards[0])