From b12d1ee7b464526febe416e80af7eed0a2b2e5a7 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 14 Jun 2026 05:09:17 +0100 Subject: [PATCH] Type Python shard log entry details --- packages/cultcache-py/PARITY.md | 4 +++- .../cultcache-py/src/cultnet_py/shard_log.py | 17 ++++++++++++++++- packages/cultcache-py/tests/test_cultcache.py | 6 ++++++ 3 files changed, 25 insertions(+), 2 deletions(-) diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index 730b22ce..c9ba76dd 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -39,7 +39,9 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. - Python CultNet shard log: Provides typed `CultNetShardLogResponse` and `CultNetShardLogEntry` helpers for inspecting mutation-log entries, resync pressure, and sequence cursors, - while cache mutation remains owned by the existing replication helpers. + including typed put-document and delete identity projections on individual + entries while cache mutation remains owned by the existing replication + helpers. `apply_shard_log_response(...)`, `CultMeshDatabase`, and `CultMeshGameSession` can consume typed shard-log responses directly for database sync and prediction reconciliation. diff --git a/packages/cultcache-py/src/cultnet_py/shard_log.py b/packages/cultcache-py/src/cultnet_py/shard_log.py index e12b9d96..70425e2d 100644 --- a/packages/cultcache-py/src/cultnet_py/shard_log.py +++ b/packages/cultcache-py/src/cultnet_py/shard_log.py @@ -3,6 +3,8 @@ from __future__ import annotations from dataclasses import dataclass from typing import Any +from .snapshot import CultNetRawDocumentRecord + @dataclass(frozen=True) class CultNetShardLogEntry: @@ -10,6 +12,9 @@ class CultNetShardLogEntry: change_kind: str put: dict[str, Any] | None = None delete: dict[str, Any] | None = None + raw_document: CultNetRawDocumentRecord | None = None + delete_schema_id: str | None = None + delete_record_key: str | None = None committed_at: str | None = None @classmethod @@ -22,11 +27,21 @@ class CultNetShardLogEntry: raise ValueError(f"unsupported shard log changeKind {change_kind!r}") put = value.get("put") delete = value.get("delete") + put_document = put.get("document") if isinstance(put, dict) else None + raw_document = ( + CultNetRawDocumentRecord.from_wire(put_document) + if isinstance(put_document, dict) + else None + ) + delete_record = dict(delete) if isinstance(delete, dict) else None return cls( sequence=sequence, change_kind=change_kind, put=dict(put) if isinstance(put, dict) else None, - delete=dict(delete) if isinstance(delete, dict) else None, + delete=delete_record, + raw_document=raw_document, + delete_schema_id=_optional_string(delete_record.get("schemaId")) if delete_record is not None else None, + delete_record_key=_optional_string(delete_record.get("recordKey")) if delete_record is not None else None, committed_at=_optional_string(value.get("committedAt")), ) diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index dc3eeec4..5af8c118 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -1076,6 +1076,10 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(response.last_sequence, 3) self.assertFalse(response.resync_required) self.assertEqual(response.entries[0].put["document"]["recordKey"], "note:1") + self.assertIsInstance(response.entries[0].raw_document, CultNetRawDocumentRecord) + self.assertEqual(response.entries[0].raw_document.record_key, "note:1") + self.assertEqual(response.entries[1].delete_schema_id, "schema-note") + self.assertEqual(response.entries[1].delete_record_key, "note:1") self.assertEqual(response.to_wire()["entries"][1]["delete"]["recordKey"], "note:1") self.assertIs(response.require_usable(), response) @@ -2024,6 +2028,8 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(shard_log["entries"][0]["changeKind"], "added") self.assertEqual(typed_shard_log.last_sequence, 1) self.assertEqual(typed_shard_log.entries[0].put["document"]["recordKey"], "note:1") + self.assertIsInstance(typed_shard_log.entries[0].raw_document, CultNetRawDocumentRecord) + self.assertEqual(typed_shard_log.entries[0].raw_document.record_key, "note:1") self.assertEqual(fetched_verses[0].verse_id, "server-verse") self.assertEqual(fetched_peers[0].peer_id, "mesh-server") self.assertIsInstance(subscription_snapshot, CultNetRawSnapshotResponse)