From a2ec06f90e3645a82a414fd65581167505eb72be Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 27 Jun 2026 20:52:26 +0100 Subject: [PATCH] Resolve Python node document aliases transparently --- packages/cultcache-py/README.md | 14 ++++ packages/cultcache-py/src/cultmesh_py/node.py | 73 ++++++++++++++----- packages/cultcache-py/tests/test_cultcache.py | 40 ++++++++++ packages/cultmesh-ts/README.md | 19 +++++ src/GameCult.Mesh/docs/public-api.md | 39 +++++----- 5 files changed, 147 insertions(+), 38 deletions(-) diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 265eecb7..cd1427d6 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -300,6 +300,20 @@ delete_message = node.database.delete_raw_message(note_doc, "note:2", shard_id=" shard_log_response = node.database.build_shard_log_response(shard_id="interop", shard_epoch=1) shard_log_wire = node.database.create_shard_log_response(shard_id="interop", shard_epoch=1) +station_stock_doc = define_database_entry_type( + "aetheria.station_stock", + [("missiles", 0), ("coolant", 1)], + schema_id="gamecult.aetheria.station_stock.v1", +) +station_stock_ui_doc = define_database_entry_type( + "aetheria.station_stock.ui", + [("missiles", 0), ("coolant", 1)], + schema_id="gamecult.aetheria.station_stock.v1", +) +node.database.register_document(station_stock_doc) +node.database.put(station_stock_ui_doc, "station:starbridge:stock", {"missiles": 24, "coolant": 80}) +stock = node.database.get_required(station_stock_ui_doc, "station:starbridge:stock") + peers = CultMesh.create_peer_catalog() response = peers.create_response(peer_exchange_request("pex-1", verse_id="local")) lease_verifier = CultMeshHmacAuthorityLeaseVerifier({"odin": b"shared-lease-key"}) diff --git a/packages/cultcache-py/src/cultmesh_py/node.py b/packages/cultcache-py/src/cultmesh_py/node.py index b567ca82..b6c3495a 100644 --- a/packages/cultcache-py/src/cultmesh_py/node.py +++ b/packages/cultcache-py/src/cultmesh_py/node.py @@ -6,6 +6,7 @@ from pathlib import Path from typing import Any, Callable from cultcache_py import CultCache, CultCacheEnvelope, SingleFileMessagePackBackingStore +from cultcache_py.cache import CultCacheError from cultcache_py.documents import DocumentDefinition, extract_value from cultnet_py import ( CultNetAppliedRecord, @@ -268,6 +269,7 @@ class CultMeshDatabase: key: str, callback: Callable[[CultMeshDatabaseChange], None], ) -> Callable[[], None]: + document = self._resolve_document_alias(document) return self.watch(callback, document=document, key=key) def watch_global( @@ -283,6 +285,7 @@ class CultMeshDatabase: name: str, callback: Callable[[CultMeshDatabaseChange], None], ) -> Callable[[], None]: + document = self._resolve_document_alias(document) if not name: raise ValueError("Name watch values must be non-empty") if document.name is None: @@ -301,6 +304,7 @@ class CultMeshDatabase: value: str, callback: Callable[[CultMeshDatabaseChange], None], ) -> Callable[[], None]: + document = self._resolve_document_alias(document) if not index: raise ValueError("Index watch aliases must be non-empty") if not value: @@ -329,9 +333,11 @@ class CultMeshDatabase: self._shard_log_store = store def put(self, document: DocumentDefinition[Any], key: str, value: Any) -> None: - previous = self.cache.get(document, key) - self.cache.put(document, key, value) - self._publish_local_change(document, key, "added" if previous is None else "updated", value, previous) + registered = self._resolve_document_alias(document) + parsed = document.decode_payload(document.encode_payload(value)) + previous = self.cache.get(registered, key) + self.cache.put(registered, key, parsed) + self._publish_local_change(registered, key, "added" if previous is None else "updated", parsed, previous) def put_global(self, document: DocumentDefinition[Any], value: Any) -> None: self.put(document, self.cache.GLOBAL_KEY, value) @@ -346,17 +352,19 @@ class CultMeshDatabase: shard_id: str | None = None, shard_epoch: int | None = None, ) -> CultNetMessage: - catalog_entry = document.catalog_entry() - previous = self.cache.get(document, key) + registered = self._resolve_document_alias(document) + parsed = document.decode_payload(document.encode_payload(value)) + catalog_entry = registered.catalog_entry() + previous = self.cache.get(registered, key) envelope = CultCacheEnvelope.create( key=key, - type=document.type, - payload=document.encode_payload(value), + type=registered.type, + payload=registered.encode_payload(parsed), schema_id=catalog_entry.schema_id, catalog_entry=catalog_entry, ) - value = self.cache.put_envelope(document, envelope) - self._publish_local_change(document, key, "added" if previous is None else "updated", value, previous) + value = self.cache.put_envelope(registered, envelope) + self._publish_local_change(registered, key, "added" if previous is None else "updated", value, previous) message = document_put_raw( message_id=message_id, key=key, @@ -371,22 +379,27 @@ class CultMeshDatabase: return message def get(self, document: DocumentDefinition[Any], key: str) -> Any: - return self.cache.get(document, key) + value = self.cache.get(self._resolve_document_alias(document), key) + return None if value is None else document.decode_payload(document.encode_payload(value)) def get_required(self, document: DocumentDefinition[Any], key: str) -> Any: - return self.cache.get_required(document, key) + value = self.get(document, key) + if value is None: + raise CultCacheError(f"Missing {document.type}:{key}") + return value def get_global(self, document: DocumentDefinition[Any]) -> Any: - return self.cache.get_global(document) + return self.get(document, self.cache.GLOBAL_KEY) def get_required_global(self, document: DocumentDefinition[Any]) -> Any: - return self.cache.get_required_global(document) + return self.get_required(document, self.cache.GLOBAL_KEY) def delete(self, document: DocumentDefinition[Any], key: str) -> None: - previous = self.cache.get(document, key) - self.cache.delete(document, key) + registered = self._resolve_document_alias(document) + previous = self.cache.get(registered, key) + self.cache.delete(registered, key) if previous is not None: - self._publish_local_change(document, key, "removed", None, previous) + self._publish_local_change(registered, key, "removed", None, previous) def delete_global(self, document: DocumentDefinition[Any]) -> None: self.delete(document, self.cache.GLOBAL_KEY) @@ -400,7 +413,8 @@ class CultMeshDatabase: shard_id: str | None = None, shard_epoch: int | None = None, ) -> CultNetMessage: - schema_id = document.catalog_entry().schema_id + registered = self._resolve_document_alias(document) + schema_id = registered.catalog_entry().schema_id self.delete(document, key) message = document_delete( message_id=message_id, @@ -716,7 +730,7 @@ class CultMeshDatabase: def _publish(self, change: CultMeshDatabaseChange) -> None: for document, key, callback in list(self._subscribers): - if document is not None and document.type != change.document.type: + if document is not None and not self._documents_alias(document, change.document): continue if key is not None and key != change.record_key: continue @@ -828,6 +842,29 @@ class CultMeshDatabase: return document return None + def _resolve_document_alias(self, document: DocumentDefinition[Any]) -> DocumentDefinition[Any]: + for registered in self.documents: + if self._documents_alias(document, registered): + return registered + return document + + def _documents_alias( + self, + left: DocumentDefinition[Any], + right: DocumentDefinition[Any], + ) -> bool: + if left.type == right.type: + return True + left_entry = left.catalog_entry() + right_entry = right.catalog_entry() + if left_entry.schema_id == right_entry.schema_id: + return True + if left_entry.schema_name == right_entry.schema_name and left_entry.schema_version == right_entry.schema_version: + return True + if left_entry.schema_id in right_entry.compatible_schema_ids: + return True + return right_entry.schema_id in left_entry.compatible_schema_ids + def _change_matches_extractor( self, change: CultMeshDatabaseChange, diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index 1f5660ec..c0fc2c49 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -2019,6 +2019,46 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(delete["shardId"], "mesh") self.assertEqual(delete["shardEpoch"], 1) + def test_cultmesh_node_resolves_same_schema_aliases_for_local_state(self) -> None: + document = define_database_entry_type( + "mesh.alias_note", + [("body", 0)], + schema_id="mesh.alias_note.v1", + schema_name="mesh.alias_note", + schema_version="mesh.alias_note.v1", + ) + alias = define_database_entry_type( + "mesh.alias_note.ui", + [("body", 0)], + schema_id="mesh.alias_note.v1", + schema_name="mesh.alias_note", + schema_version="mesh.alias_note.v1", + ) + node = create_node(runtime_id="python-node") + node.register_document(document) + seen: list[CultMeshDatabaseChange] = [] + node.database.watch_record(alias, "note:alias", seen.append) + + node.put(alias, "note:alias", {"body": "from-alias-put"}) + self.assertEqual(node.get_required(document, "note:alias")["body"], "from-alias-put") + self.assertEqual(node.get_required(alias, "note:alias")["body"], "from-alias-put") + self.assertEqual(seen[0].document.type, document.type) + self.assertEqual(seen[0].value["body"], "from-alias-put") + + put = node.put_raw_message( + alias, + "note:alias", + {"body": "from-alias-raw-put"}, + message_id="alias-put", + ).to_wire() + self.assertEqual(put["document"]["schemaId"], "mesh.alias_note.v1") + self.assertEqual(put["document"]["recordKey"], "note:alias") + self.assertEqual(node.get_required(alias, "note:alias")["body"], "from-alias-raw-put") + + delete = node.delete_raw_message(alias, "note:alias", message_id="alias-delete").to_wire() + self.assertEqual(delete["schemaId"], "mesh.alias_note.v1") + self.assertIsNone(node.get(alias, "note:alias")) + def test_cultnet_document_delete_helper_matches_schema_v0_shape(self) -> None: message = document_delete( message_id="delete-1", diff --git a/packages/cultmesh-ts/README.md b/packages/cultmesh-ts/README.md index a6dbf6c8..5ffc1033 100644 --- a/packages/cultmesh-ts/README.md +++ b/packages/cultmesh-ts/README.md @@ -87,6 +87,25 @@ await input.submitPrediction("pilot-a", predictedInput); const stop = input.watch("pilot-a", latest => reconcileInput(latest)); ``` +Durable nodes resolve same-schema aliases at the boundary. Register the +canonical document that owns storage and replication, then ask the node for the +typed view the current runtime wants: + +```ts +const station = await CultMesh.startNode(statePath, { + documents: [stationStockDocument], +}); + +const stock = station.document(stationStockUiDocument, "station:starbridge:stock"); +const current = await stock.latest(); + +await stock.set(updatedStockFromUi); + +const reactive = station.reactiveDocument(stationStockUiDocument, "station:starbridge:stock"); +await reactive.ready; +reactive.current.availableMissiles -= 4; +``` + State pointers are the same kind of managed surface for UI and tools. They can advertise source documents, inherit a Verse route when bound, and resolve through that Verse without caller-side context plumbing: diff --git a/src/GameCult.Mesh/docs/public-api.md b/src/GameCult.Mesh/docs/public-api.md index 52df0845..1b592748 100644 --- a/src/GameCult.Mesh/docs/public-api.md +++ b/src/GameCult.Mesh/docs/public-api.md @@ -170,9 +170,11 @@ portable machinery that makes it feel native. `CultCache` record, a distributed `CultNetDatabase` record, or a `CultMeshNode` record through the same surface instead of walking transport and projection layers themselves. Same-schema CLR aliases can be requested - with `AsSchemaAlias()`; CultMesh verifies the shared - `[CultDocument(schemaName, schemaVersion)]` identity and uses the shared - CultCache MessagePack codec for read/watch/replace/prediction conversion. + directly from node/database/snapshot surfaces; CultMesh resolves the canonical + registered document by shared `[CultDocument(schemaName, schemaVersion)]` + identity and uses the shared CultCache MessagePack codec for + read/watch/replace/prediction conversion. `AsSchemaAlias()` remains + available when a caller already has a handle and wants to project it. - `CultMeshDocumentCatalog` is the schema-aware lookup edge for a set of document handles. It indexes handles by CLR document type, schema name, and schema version, and resolves same-schema CLR aliases by delegating to @@ -236,19 +238,19 @@ var objects = await visibleObjects.ExecuteAsync(viewportRequest); await movePilot.InvokeAsync(moveRequest, idempotencyKey); ``` -A single typed document can be surfaced the same way: +A single typed document can be surfaced the same way. The caller asks for the +typed view it wants; if that type is a same-schema alias of the registered +canonical document, CultMesh still opens the correct backing record: ```csharp -var stationStock = CultMesh.Document( +var stockForUi = CultMesh.Document( node, new CultRecordKey("station:starbridge:stock"), verse); -var stock = await stationStock.LatestAsync(); -using var watch = stationStock.Watch(RenderStock); - -var uiAlias = stationStock.AsSchemaAlias(); -await uiAlias.ReplaceAsync(updatedStockFromUi); +var stock = await stockForUi.LatestAsync(); +using var watch = stockForUi.Watch(RenderStock); +await stockForUi.SetAsync(updatedStockFromUi); ``` Projected or derived documents can use the same handle shape with explicit @@ -293,7 +295,8 @@ read when another runtime generated a different schema id for a compatible schema alias. The decode path prefers exact schema id matches when present and falls back to the requested record key. -A domain facade can collect handles into one schema-aware catalog: +A domain facade can still collect existing handles into one schema-aware +catalog when it is composing pre-built surfaces: ```csharp var documents = CultMesh.Documents( @@ -340,20 +343,16 @@ const station = await CultMesh.startNode(statePath, { documents: [stationStockDocument, currentDockingDocument], }); -const stock = station.document(stationStockDocument, "station:starbridge:stock"); +const stock = station.document(stationStockUiDocument, "station:starbridge:stock"); const docking = station.document(currentDockingDocument, "player:raven:docking"); const catalog = CultMesh.documents(stock, docking); -const stockUi = catalog.document(stationStockUiDocument, { - parse: value => stationStockUiDocument.schema.parse(value), -}); - -const currentStock = await stockUi.latest(); -const unsubscribe = stockUi.watch(next => renderStock(next)); -await stockUi.replace(updatedStock); +const currentStock = await stock.latest(); +const unsubscribe = stock.watch(next => renderStock(next)); +await stock.set(updatedStock); unsubscribe(); -const pilots = station.collection(playerShipDocument); +const pilots = station.collection(playerShipUiDocument); const currentPilots = await pilots.latest(); const stopRoster = pilots.watchChanges(change => refreshRoster(change));