diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index f5925e82..43499a13 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -32,6 +32,8 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. facade. Change notifications carry previous values when the database can observe the old record before local or replicated application. + It can project local envelopes into schema-v0 raw snapshot responses and apply + those responses back through the shared CultNet replication path. - Python CultMesh committed simulation facts: The live interop harness sends Python a simulation observation, receives a consensus candidate, then requests the committed `gamecult.mesh.simulation_fact` @@ -76,3 +78,6 @@ node --test packages\cultnet-ts\dist-test\test\interop\cultnet-interop.test.js - Python does not implement the full C# daemon/server stack. Its current role is package runtime, raw interop peer, local CultMesh session facade, and typed state participant. +- Python does not claim the full C# shard mutation-log service surface. It can + create/apply raw snapshots and consume shard-log responses, while the live + interop peer owns its harness mutation log. diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 4e6b1047..7bebbd70 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -241,6 +241,7 @@ put_message = node.database.put_raw_message( shard_id="interop", shard_epoch=1, ) +snapshot_response = node.database.create_snapshot_response(schema_ids=[note_doc.catalog_entry().schema_id]) delete_message = node.database.delete_raw_message(note_doc, "note:2", shard_id="interop", shard_epoch=1) peers = CultMesh.create_peer_catalog() diff --git a/packages/cultcache-py/src/cultmesh_py/node.py b/packages/cultcache-py/src/cultmesh_py/node.py index f7f53e4e..bc29987a 100644 --- a/packages/cultcache-py/src/cultmesh_py/node.py +++ b/packages/cultcache-py/src/cultmesh_py/node.py @@ -104,6 +104,25 @@ class CultMeshNode: def snapshot(self) -> dict[str, dict[str, Any]]: return self.database.snapshot() + def create_snapshot_response( + self, + *, + message_id: str = "", + schema_ids: list[str] | None = None, + record_keys: list[str] | None = None, + shard_id: str | None = None, + shard_epoch: int | None = None, + shard_log_sequence: int | None = None, + ) -> dict[str, Any]: + return self.database.create_snapshot_response( + message_id=message_id, + schema_ids=schema_ids, + record_keys=record_keys, + shard_id=shard_id, + shard_epoch=shard_epoch, + shard_log_sequence=shard_log_sequence, + ) + def pull(self) -> None: self.database.pull() @@ -321,6 +340,46 @@ class CultMeshDatabase: def snapshot(self) -> dict[str, dict[str, Any]]: return self.cache.snapshot() + def create_snapshot_response( + self, + *, + message_id: str = "", + schema_ids: list[str] | None = None, + record_keys: list[str] | None = None, + shard_id: str | None = None, + shard_epoch: int | None = None, + shard_log_sequence: int | None = None, + ) -> dict[str, Any]: + requested_schema_ids = set(schema_ids or []) + requested_record_keys = set(record_keys or []) + documents = [] + for envelope in self.cache.snapshot_envelopes(): + schema_id = envelope.schema_id or envelope.type + if requested_schema_ids and schema_id not in requested_schema_ids: + continue + if requested_record_keys and envelope.key not in requested_record_keys: + continue + documents.append({ + "schemaId": schema_id, + "recordKey": envelope.key, + "storedAt": envelope.stored_at, + "payloadEncoding": "messagepack", + "payload": envelope.payload, + }) + + response: dict[str, Any] = { + "schemaVersion": "cultnet.snapshot_response_raw.v0", + "messageId": message_id, + "documents": documents, + } + if shard_id is not None: + response["shardId"] = shard_id + if shard_epoch is not None: + response["shardEpoch"] = shard_epoch + if shard_log_sequence is not None: + response["shardLogSequence"] = shard_log_sequence + return response + def pull(self) -> None: self.cache.pull_all_backing_stores() diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index 25b0be30..092db6ed 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -940,6 +940,42 @@ class CultCacheTests(unittest.TestCase): with self.assertRaises(Exception): node.database.put(document, "settings:wrong", {"theme": "bad"}) + def test_cultmesh_database_creates_raw_snapshot_response_from_envelopes(self) -> None: + document = define_database_entry_type( + "mesh.snapshot_note", + [("body", 0)], + schema_id="mesh.snapshot_note.v1", + ) + source = CultMesh.create_node(runtime_id="mesh-snapshot-source") + source.database.register_document(document) + source.database.put(document, "note:1", {"body": "include"}) + source.database.put(document, "note:2", {"body": "skip"}) + + response = source.database.create_snapshot_response( + message_id="snapshot-1", + schema_ids=["mesh.snapshot_note.v1"], + record_keys=["note:1"], + shard_id="notes", + shard_epoch=4, + shard_log_sequence=7, + ) + + self.assertEqual(response["schemaVersion"], "cultnet.snapshot_response_raw.v0") + self.assertEqual(response["messageId"], "snapshot-1") + self.assertEqual(response["shardId"], "notes") + self.assertEqual(response["shardEpoch"], 4) + self.assertEqual(response["shardLogSequence"], 7) + self.assertEqual([record["recordKey"] for record in response["documents"]], ["note:1"]) + self.assertEqual(response["documents"][0]["schemaId"], "mesh.snapshot_note.v1") + self.assertEqual(response["documents"][0]["payloadEncoding"], "messagepack") + + target = CultMesh.create_node(runtime_id="mesh-snapshot-target") + target.database.register_document(document) + applied = target.database.apply_snapshot_response(response) + self.assertEqual([(record.schema_id, record.record_key) for record in applied], [("mesh.snapshot_note.v1", "note:1")]) + self.assertEqual(target.database.get_required(document, "note:1"), {"body": "include"}) + self.assertIsNone(target.database.get(document, "note:2")) + def test_cultmesh_database_watchers_observe_name_and_index_changes(self) -> None: document = define_database_entry_type( "mesh.named_watch",