Reconcile Python CultMesh predictions
This commit is contained in:
parent
e863902e76
commit
90a669914b
6 changed files with 161 additions and 8 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
21
packages/cultcache-py/src/cultnet_py/prediction.py
Normal file
21
packages/cultcache-py/src/cultnet_py/prediction.py
Normal 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))
|
||||
)
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue