Reconcile Python CultMesh predictions

This commit is contained in:
Meta Vens 2026-06-14 00:47:41 +01:00
commit 90a669914b
6 changed files with 161 additions and 8 deletions

View file

@ -210,12 +210,13 @@ python -m cultnet_py.interop_peer probe --runtime-id python-prober --discovery-p
`cultmesh_py` includes a local cache-backed node, schema-v0 helpers for the
CultMesh Verse catalog and peer exchange wire messages, local authority lease
checks, stream transport negotiation, and committed simulation fact documents:
checks, stream transport negotiation, committed simulation fact documents, and
local prediction reconciliation:
```python
from cultcache_py import define_database_entry_type
from cultnet_py import CultNetRawClient
from cultmesh_py import CultMesh, CultMeshDiscoveryClient, peer_exchange_request
from cultnet_py import CultNetClientAuthorityScope, CultNetRawClient
from cultmesh_py import CultMesh, CultMeshDiscoveryClient, CultMeshGameSessionOptions, peer_exchange_request
note_doc = define_database_entry_type("mesh.note", [("body", 0)])
node = CultMesh.start_node("mesh.cc", runtime_id="python-runtime")
@ -255,8 +256,16 @@ committed = facts.commit({
"hasQuorum": True,
})
session = CultMesh.create_game_session(node)
session = CultMesh.create_game_session(
node,
CultMeshGameSessionOptions(
client_authority_scopes=(
CultNetClientAuthorityScope("python-runtime", schema_ids=(note_doc.catalog_entry().schema_id,), key_prefix="input:python"),
),
),
)
session_commits = session.submit_and_commit(observation.to_wire())
prediction = session.predict(note_doc, "input:python:move", {"body": "predicted input"})
```
## Wire Parity
@ -286,8 +295,9 @@ Current receipts:
- `packages/cultcache-py/tests/test_cultcache.py` covers Python CultMesh
Verse catalog, peer exchange, authority lease, stream negotiation, CultNet
helper shapes, raw snapshot/shard-log application, simulation claim hashing,
consensus aggregation, game-session fact commits, committed simulation fact
payload slots, and witness artifact bundle payload slots.
consensus aggregation, game-session fact commits, local prediction
reconciliation, committed simulation fact payload slots, and witness artifact
bundle payload slots.
- `cultcache_py`, `cultnet_py`, and `cultmesh_py` ship `py.typed` markers so
downstream type checkers can inspect the package surface instead of treating
the runtime as an untyped xenos swamp.

View file

@ -5,6 +5,7 @@ from .session import (
CultMeshGameSession,
CultMeshGameSessionOptions,
CultMeshPrediction,
CultMeshSessionChange,
)
from .simulation import (
SIMULATION_FACT_DOCUMENT_TYPE,
@ -45,6 +46,7 @@ __all__ = [
"CultMeshPeerCard",
"CultMeshPeerCatalog",
"CultMeshPrediction",
"CultMeshSessionChange",
"CultMeshSimulationFact",
"CultMeshSimulationFactCommit",
"CultMeshSimulationFactCommitter",

View file

@ -4,7 +4,14 @@ from dataclasses import dataclass
from typing import Any
from cultcache_py.documents import DocumentDefinition
from cultnet_py import CultNetSimulationConsensusOptions, CultNetSimulationObservationHub
from cultnet_py import (
CultNetAppliedRecord,
CultNetClientAuthorityScope,
CultNetRawClient,
CultNetSimulationConsensusOptions,
CultNetSimulationObservationHub,
apply_shard_log_response,
)
from .node import CultMeshNode
from .simulation import (
@ -19,16 +26,26 @@ from .wire import CultMeshAuthorityLeaseCatalog, CultMeshPeerCatalog, CultMeshVe
@dataclass(frozen=True)
class CultMeshPrediction:
key: str
schema_id: str
document: DocumentDefinition[Any]
value: Any
@dataclass(frozen=True)
class CultMeshSessionChange:
schema_id: str
record_key: str
change_kind: str
value: Any | None = None
@dataclass
class CultMeshGameSessionOptions:
verse_catalog: CultMeshVerseCatalog | None = None
peer_catalog: CultMeshPeerCatalog | None = None
authority_leases: CultMeshAuthorityLeaseCatalog | None = None
consensus_options: CultNetSimulationConsensusOptions | None = None
client_authority_scopes: tuple[CultNetClientAuthorityScope, ...] = ()
@dataclass
@ -46,10 +63,40 @@ class CultMeshGameSession:
)
self.fact_committer = CultMeshSimulationFactCommitter(self.node)
self._committed_fact_ids: set[str] = set()
self._client_authority_scopes = tuple(options.client_authority_scopes)
self._predicted_keys: set[tuple[str, str]] = set()
def predict(self, document: DocumentDefinition[Any], key: str, value: Any) -> CultMeshPrediction:
schema_id = document.catalog_entry().schema_id
if not any(scope.matches(self.node.runtime_id, schema_id, key) for scope in self._client_authority_scopes):
raise ValueError(
f"Runtime {self.node.runtime_id!r} does not have client prediction authority "
f"for schema {schema_id!r} key {key!r}"
)
self.node.put(document, key, value)
return CultMeshPrediction(key=key, document=document, value=value)
self._predicted_keys.add((schema_id, key))
return CultMeshPrediction(key=key, schema_id=schema_id, document=document, value=value)
def apply_shard_log_response(self, response: dict[str, Any]) -> list[CultMeshSessionChange]:
applied = apply_shard_log_response(self.node.cache, self.node.documents, response)
return self._reconcile_applied(applied)
def sync_shard_log(
self,
client: CultNetRawClient,
*,
shard_id: str,
shard_epoch: int | None = None,
after_sequence: int = 0,
limit: int | None = None,
) -> list[CultMeshSessionChange]:
response = client.fetch_shard_log(
shard_id=shard_id,
shard_epoch=shard_epoch,
after_sequence=after_sequence,
limit=limit,
)
return self.apply_shard_log_response(response)
def submit_observation(self, observation_or_message: dict[str, Any]) -> list[dict[str, Any]]:
return self.observation_hub.submit(observation_or_message)
@ -73,3 +120,19 @@ class CultMeshGameSession:
self._committed_fact_ids.add(fact_id)
commits.append(commit)
return commits
def _reconcile_applied(self, applied: list[CultNetAppliedRecord]) -> list[CultMeshSessionChange]:
changes: list[CultMeshSessionChange] = []
for record in applied:
key = (record.schema_id, record.record_key)
change_kind = record.change_kind
if key in self._predicted_keys and record.change_kind in {"added", "updated"}:
self._predicted_keys.remove(key)
change_kind = "reconciled"
changes.append(CultMeshSessionChange(
schema_id=record.schema_id,
record_key=record.record_key,
change_kind=change_kind,
value=record.value,
))
return changes

View file

@ -18,6 +18,7 @@ from .messages import (
snapshot_request,
witness_artifact_bundle,
)
from .prediction import CultNetClientAuthorityScope
from .replication import (
CultNetAppliedRecord,
apply_raw_document_record,
@ -36,6 +37,7 @@ __all__ = [
"CultNetDatabaseSubscription",
"CultNetRawClient",
"CultNetAppliedRecord",
"CultNetClientAuthorityScope",
"CultNetSimulationConsensus",
"CultNetSimulationConsensusOptions",
"CultNetSimulationObservationHub",

View file

@ -0,0 +1,21 @@
from __future__ import annotations
from dataclasses import dataclass
@dataclass(frozen=True)
class CultNetClientAuthorityScope:
owner_runtime_id: str
schema_ids: tuple[str, ...] = ()
key_prefix: str | None = None
def __post_init__(self) -> None:
if not self.owner_runtime_id.strip():
raise ValueError("owner_runtime_id must be non-empty")
def matches(self, runtime_id: str, schema_id: str, record_key: str) -> bool:
return (
self.owner_runtime_id == runtime_id
and (not self.schema_ids or schema_id in self.schema_ids)
and (self.key_prefix is None or record_key.startswith(self.key_prefix))
)

View file

@ -20,6 +20,7 @@ from cultcache_py.benchmark import run_benchmark
from cultcache_py.interop import read_note, write_note
from cultnet_py import (
compute_simulation_claim_hash,
CultNetClientAuthorityScope,
CultNetRawClient,
CultNetSimulationConsensusOptions,
apply_raw_snapshot,
@ -961,6 +962,60 @@ class CultCacheTests(unittest.TestCase):
self.assertEqual(stored.claim_hash, claim_hash)
self.assertEqual(stored.witness_count, 2)
def test_cultmesh_game_session_prediction_requires_scope_and_reconciles_shard_log(self) -> None:
note_doc = define_database_entry_type(
"mesh.input",
[("body", 0)],
schema_id="mesh.input.v1",
)
with tempfile.TemporaryDirectory() as tmp:
node = CultMesh.create_node(Path(tmp) / "prediction.cc", runtime_id="client-a")
node.register_document(note_doc)
session = CultMesh.create_game_session(
node,
CultMeshGameSessionOptions(
client_authority_scopes=(
CultNetClientAuthorityScope(
"client-a",
schema_ids=("mesh.input.v1",),
key_prefix="input:client-a",
),
)
),
)
with self.assertRaisesRegex(ValueError, "does not have client prediction authority"):
session.predict(note_doc, "input:other", {"body": "nope"})
prediction = session.predict(note_doc, "input:client-a:move", {"body": "predicted"})
put = document_put_raw(
message_id="authoritative",
key=prediction.key,
schema_id=prediction.schema_id,
stored_at="2026-06-13T00:00:00Z",
payload=note_doc.encode_payload({"body": "authoritative"}),
shard_id="inputs",
shard_epoch=1,
)
changes = session.apply_shard_log_response({
"schemaVersion": "cultnet.shard_log_response.v0",
"messageId": "inputs-log",
"shardId": "inputs",
"shardEpoch": 1,
"entries": [
{
"sequence": 1,
"committedAt": "2026-06-13T00:00:00Z",
"changeKind": "updated",
"put": put.to_wire(),
}
],
"resyncRequired": False,
})
self.assertEqual(changes[0].change_kind, "reconciled")
self.assertEqual(node.get_required(note_doc, prediction.key)["body"], "authoritative")
def test_cultmesh_verse_catalog_response_matches_schema_v0_wire_shape(self) -> None:
import msgpack # type: ignore