Resolve Python node document aliases transparently

This commit is contained in:
Meta Vens 2026-06-27 20:52:26 +01:00
commit a2ec06f90e
5 changed files with 147 additions and 38 deletions

View file

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

View file

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

View file

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

View file

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

View file

@ -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<TAlias>()`; 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<TAlias>()` 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<StationStockDocument>(
var stockForUi = CultMesh.Document<StationStockUiDocument>(
node,
new CultRecordKey("station:starbridge:stock"),
verse);
var stock = await stationStock.LatestAsync();
using var watch = stationStock.Watch(RenderStock);
var uiAlias = stationStock.AsSchemaAlias<StationStockUiDocument>();
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));