# CultMesh Public API Package: `GameCult.Mesh` Brand: CultMesh Namespace: `GameCult.Mesh` ## Entry Points - `CultMesh.CreateNodeAsync(...)` - `CultMesh.StartNodeAsync(...)` - `CultMesh.CreateVerseCatalog()` - `CultMesh.CreatePeerCatalog()` - `CultMesh.CreateVerseDiscoveryClient(...)` - `CultMesh.CreatePeerExchangeClient(...)` - `CultMesh.CreateAuthorityLeaseCatalog()` - `CultMesh.ParseRudpEndpoint(...)` - `CultMesh.CreateRudpServer(...)` - `CultMesh.CreateRudpClient(...)` - `CultMesh.CreateRudpClientForPeer(...)` - `CultMesh.CreateRudpClientForAuthorizedPeer(...)` - `CultMesh.ConnectRudpClient(...)` - `CultMesh.ConnectRudpClientForPeer(...)` - `CultMesh.ConnectRudpClientForAuthorizedPeer(...)` - `CultMesh.CreateSimulationFactCommitter(...)` - `CultMesh.CreateGameSession(...)` - `CultMesh.CreateClient(...)` - `CultMesh.ConnectClient(...)` `CultMeshNode` wraps the current local runtime pieces: - `Cache`: the underlying `CultCache` - `Server`: the underlying CultNet server - `Database`: the distributed realtime database facade - `DatabaseServer`: the schema-v0 database bridge `CultMeshNodeOptions.EnableDurableShardLogs` attaches a file-backed authoritative shard-log store when `DatabaseOptions.MutationLogStore` is not already supplied. `ShardLogPath` can override the location; otherwise CultMesh uses a `.cultmesh/shard-logs` directory beside the cache file. The package home and primary entrypoint are `GameCult.Mesh` / `CultMesh`. Some lower-level database and wire-contract types still retain `CultNet` names because they are shared with the transport package. Treat those as plumbing, not the brand surface. ## Core Behaviors ### Verses `CultMeshVerseDescriptor` describes a rule-bearing consensus graph. It includes transport compatibility, rules hash, authority model, discovery endpoints, known authority runtimes, optional parent Verse id, and plugin requirements. `CultMeshVerseCatalog` is the local reactive catalog for discovered Verses. It can publish discovery updates and find compatible transfer targets. `CultMesh.ServeVerseCatalog(node, catalog)` attaches schema-v0 Verse discovery responses to a node. The wire contracts are `cultmesh.verse_catalog_request.v0` and `cultmesh.verse_catalog_response.v0`. Consumers can apply a response directly with `CultMeshVerseCatalog.Upsert(CultMeshVerseCatalogResponseMessage)`. ### Peer Exchange `CultMeshPeerCatalog` is the local reactive catalog for peer cards. `CultMeshPeerCard` describes a candidate peer endpoint for one Verse with roles, shard hints, optional region, optional authority lease id, expiry, and signature. `CultMesh.ServePeerExchange(node, catalog)` attaches schema-v0 peer exchange responses to a node. The wire contracts are `cultmesh.peer_exchange_request.v0` and `cultmesh.peer_exchange_response.v0`. `CultMeshPeerExchangeClient` can fetch peer cards from known endpoints and upsert them into a local catalog. Peer cards are discovery hints; authority still requires a valid lease or signature for the target Verse. `CultMeshPeerCatalog.FindAuthorized(...)` and `FirstAuthorized(...)` compose peer lookup with `CultMeshAuthorityLeaseCatalog.IsAuthorized(...)`. ### Authority Leases `CultMeshAuthorityLease` grants one peer specific roles for a Verse, optionally scoped to shard ids and bounded by time. `CultMeshAuthorityLeaseCatalog` checks whether a peer card is authorized for a requested role and shard. This keeps peer exchange separate from authority instead of letting contact gossip mutate the world. ### Cross-Runtime Primitives These are the first shared primitives for the cozy typed Verse surface that projects like Aetheria should build on instead of inventing daemon-specific adapters: In CultMesh, a primitive can be more than a data shape. Useful state-access patterns should graduate into shared managed affordances: typed handles, generated binding metadata, route selection, authority context, watches, diagnostics, and native-view descriptors that let each runtime use the same semantic API. The domain package names the thing; CultMesh supplies the fast, portable machinery that makes it feel native. - `CultMeshStatePointer` is a typed pointer to Verse state that UI surfaces, tools, and clients can resolve or watch without string state-ref plumbing. `CultMesh.StatePointer(...)` creates simple or context-aware pointers. Pointers carry source descriptors and route hints, and `CultMesh.DescribeStatePointer(...)` exposes that metadata for catalogs and inspectors. Context-aware pointers can bind with `Bind(...)`, `CultMesh.BindStatePointer(...)`, or `CultMeshVerse.BindStatePointer(...)`, producing a Verse-bound handle that resolves and watches through the shared Verse query context instead of forcing UI/tool code to rebuild route plumbing. - `CultMeshMutableStatePointer` extends the same state pointer shape with a typed `ReplaceAsync(...)` operation for authoritative document handles, editor tools, and UI surfaces that intentionally write state. It keeps the read/watch/replace trio in CultMesh instead of letting each domain package invent private document wrappers. `CultMesh.MutableStatePointer(...)`, `CultMesh.BindMutableStatePointer(...)`, and `CultMeshVerse.BindMutableStatePointer(...)` preserve the same Verse context, route hints, source diagnostics, and state-binding metadata as read-only pointers. - `CultMeshStateRefResolver` is the shared bridge for UI/tool surfaces that still receive state references from authored Eve/CultUI documents. Resolvers are named, composable, carry source descriptors and route hints, and expose diagnostics through `CultMesh.DescribeStateRefResolver(...)`. Legacy `Func` lowerers can use `AsFunc()` while generated surfaces migrate to typed state pointers and binding descriptors. - `CultMeshStateBindingDescriptor` and `CultMeshStateBindingRecord` are the UI/tool state edge. Live surfaces bind a component prop to a typed state pointer; persistence and transport boundaries use `CultMesh.StateBindingRecord(...)` instead of local pointer-field copies or route parsers. - `CultMeshOperationHandle` is a method-shaped operation handle. `CultMeshOperationContext`, `CultMeshAuthorityClaim`, and `CultMeshOperationReceipt` carry runtime identity, authority metadata, route hints, idempotency, acceptance, and diagnostics. `CultMesh.DescribeOperationHandle(...)` exposes the operation id for surface catalogs and generated tooling. `Bind(...)`, `CultMesh.BindOperation(...)`, and `CultMeshVerse.BindOperation(...)` produce Verse-bound handles so generated domain facades can invoke without re-threading context plumbing at every call site. - `CultMeshOperationBindingDescriptor`, `CultMeshOperationBindingRecord`, `CultMeshOperationInvocationDescriptor`, `CultMeshOperationInvocationRecord`, and `CultMeshOperationPayload` are the UI/tool operation edge. Live surfaces carry typed operation identity and scalar payload reads; persistence and transport boundaries use `CultMesh.OperationBindingRecord(...)`, `CultMesh.OperationInvocationRecord(...)`, and `CultMeshOperationPayload.ToDictionary()` instead of local route parsers or ad-hoc payload maps. - `CultMeshQuerySurface` is a typed derived-state query surface. Query execution can be local, remote, shared-memory, IPC, or WASM-routed while preserving the same semantic API. Query surfaces can also carry source descriptors, route hints, and reactive watches so tools and UI runtimes can inspect what state a generated query depends on, which route it prefers, and subscribe without inventing polling glue. Query surfaces can be bound with `Bind(...)`, `CultMesh.BindQuery(...)`, or `CultMeshVerse.BindQuery(...)`. - `CultMeshLiveFeed` is a typed live view surface for composed client snapshots such as an RTS viewport plus selection, health, and authority panels. It gives clients one `snapshot(...)` / `watch(...)` handle while preserving source descriptors and route defaults. Live feeds can be bound with `Bind(...)`, `CultMesh.BindLiveFeed(...)`, or `CultMeshVerse.BindLiveFeed(...)`. - `CultMeshDocumentHandle` is the typed reactive document edge for CultCache/CultNet state. It exposes document metadata, one coherent `LatestAsync()` read, a `Watch()` stream, and `ReplaceAsync(...)` when the handle is backed by mutable state. Callers can bind a projected live feed, a local `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 conversion. - `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 `CultMeshDocumentHandle.AsSchemaAlias()`. Domain facades can expose `Document()`, `DocumentBySchema(...)`, `LatestAsync()`, and `Watch()` without owning schema dictionaries or alias serializers. - `CultMeshCollectionHandle` is the typed reactive edge for multi-record state. It exposes one `LatestAsync()` collection snapshot and a `WatchChanges()` stream while hiding whether the backing source is an in-process `CultCache`, a distributed `CultNetDatabase`, or a `CultMeshNode`. Collection handles can represent all records of a document type, a named document view, or an indexed value view, and they support the same same-schema CLR alias conversion as document handles. - `CultMeshProjectionRecipe` names a reusable projection from typed source state into derived state. It records source handles, route hints, and projection execution, and can be exposed as a typed query surface. Reactive projection recipes preserve their watcher when exposed as query surfaces. When a caller supplies an automatic query context, the recipe route becomes the default; explicit caller routes still win. - `CultMeshNativeSliceViewDescriptor` and `CultMeshNativeSliceColumn` describe typed native views for co-located runtimes such as Unity Burst jobs, Rust slices, or browser typed arrays. `CultMesh.DescribeNativeSliceView(...)` exposes the full view id, schema id, row count, columns, route, native handle, and dense stride for tools and adapters. - `CultMeshRouteHint`, `CultMeshRouteRecord`, and `CultMeshLocalityKind` name locality choices without forcing application code to choose transport-specific APIs. `CultMesh.RouteRecord(...)` is the shared way to flatten and rehydrate route kind/description fields at persisted document, UI, tool, and transport boundaries. These types are intentionally small handles and descriptors. Generated bindings and runtime adapters should compose them into domain sugar such as `verse.aetheria().entity(id).pilot().move(...)`, `zone.objects().visibleTo(units).within(rect)`, and `renderView.AsNativeArrays()`. The C# helpers already support the first layer of that shape: ```csharp var context = CultMeshOperationContext .ForRuntime("unity-raven") .WithClaim(new CultMeshAuthorityClaim("pilot-control", shardId: "zone:local-rts")) .WithRoute(new CultMeshRouteHint(CultMeshLocalityKind.InProcess)); await moveOperation.InvokeAsync(moveRequest, context); ``` Generated facades should bind surfaces once to the correct Verse view: ```csharp var queryVerse = verse.WithRoute(new CultMeshRouteHint(CultMeshLocalityKind.SharedMemory)); var commandVerse = verse.WithRoute(new CultMeshRouteHint(CultMeshLocalityKind.Network)); var visibleObjects = queryVerse.BindQuery(objectsViewport); var movePilot = commandVerse.BindOperation(setMoveVector); var objects = await visibleObjects.ExecuteAsync(viewportRequest); await movePilot.InvokeAsync(moveRequest, idempotencyKey); ``` A single typed document can be surfaced the same way: ```csharp var stationStock = 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); ``` Projected or derived documents can use the same handle shape with explicit snapshot/watch delegates: ```csharp var cockpit = CultMesh.Document( "aetheria.ship.cockpit.current", verse, context => cockpitStore.LatestAsync(context), context => cockpitStore.Watch(context), sources: new[] { CultMesh.ProjectionSource( "pilot:cockpit", schemaId: "gamecult.aetheria.cockpit_state.v1") }); var current = await cockpit.LatestAsync(); using var subscription = cockpit.Watch(next => RenderCockpit(next)); var daemonAlias = cockpit.AsSchemaAlias(); ``` A domain facade can collect handles into one schema-aware catalog: ```csharp var documents = CultMesh.Documents( currentDocking, stationRefit, zoneContacts); var refit = await documents.LatestAsync(); var uiDocking = documents.Document(); var bySchema = documents.DocumentBySchema("gamecult.aetheria.station_refit.v1"); ``` Typed collections use the same one-call style: ```csharp var allies = CultMesh.CollectionByIndex( node, "Faction", "au"); var currentAllies = await allies.LatestAsync(); using var changes = allies.WatchChanges(change => UpdateRoster(change)); var uiAllies = allies.AsSchemaAlias(); ``` ```ts const queryVerse = verse.withRoute("shared-memory", statePath); const commandVerse = verse .withRoute("network", endpoint) .withClaim("commander-control", { shardId: "aetheria.local" }); const visibleObjects = CultMesh.bindQuery(queryVerse, queries.objectsViewport); const movePilot = CultMesh.bindOperation(commandVerse, operations.setMoveVector); const objects = await visibleObjects.execute(viewportRequest); await movePilot.invoke({ actorEntityKey, directionX: 1, directionY: 0 }); ``` Native view descriptors can name unmanaged columns without hand-entered byte sizes: ```csharp var view = new CultMeshNativeSliceViewDescriptor( "aetheria.zone.render", "gamecult.aetheria.render_body.v1", rowCount, new[] { CultMeshNativeSliceColumn.For("position"), CultMeshNativeSliceColumn.For("velocity") }, new CultMeshRouteHint(CultMeshLocalityKind.SharedMemory)); ``` Projection recipes give local projection code a shared shape before it becomes runtime-specific glue: ```csharp var objectsViewport = CultMesh.ProjectionRecipe( "aetheria.zone.objects.visible", new[] { CultMesh.ProjectionSource("daemon:aetheria.frame.latest.v1", "gamecult.aetheria.daemon_frame.v1"), CultMesh.ProjectionSource("daemon:aetheria.authority.policy.v1") }, (request, context) => ProjectObjectsAsync(request, context), new CultMeshRouteHint(CultMeshLocalityKind.SharedMemory)); var query = objectsViewport.AsQuerySurface(); ``` Calling `query.ExecuteAsync(request, "unity-raven")` inherits the recipe's shared-memory route. Calling it with a `CultMeshQueryContext` that already names `Network`, `Ipc`, `Wasm`, or another route uses the caller's route instead. `query.Sources` and `query.RouteHint` preserve the recipe metadata for diagnostics, tooling, and UI/MCP surfaces. If the projection supports reactive execution, `query.Watch(...)` / `query.watch(...)` keeps the same projection route resolution, so a browser map tab, Unity renderer, Eve surface, or MCP tool can subscribe through the same typed query affordance it uses for one-shot reads. `CultMesh.DescribeQuerySurface(...)` and `CultMesh.DescribeProjectionRecipe(...)` expose the same metadata in a stable diagnostic shape for generated clients, Eve/CultUI inspectors, MCP tools, and surface catalogs. Tooling should ask CultMesh for these descriptors instead of copying source lists and route hints by convention. `CultMesh.DescribeSurface(...)` and `CultMesh.DescribeSurfaceCatalog(...)` collect query surfaces, projection recipes, live feeds, operations, state pointers, and native views into one inspectable catalog for a runtime or generated binding package. State pointers are advertised by pointer id; native slice views are advertised by view id and route while the full column layout stays in `CultMeshNativeSliceViewDescriptor`. Catalog diagnostics support exact id lookup and kind filtering so tools can discover, for example, every operation or native view without local scan conventions. `CultMesh.DescribeSurfaceCatalogIndex(...)` / TS `CultMesh.surfaceCatalogIndex(...)` promotes that grouping into a shared diagnostic shape with `queries`, `projectionRecipes`, `liveFeeds`, `operations`, `statePointers`, and `nativeSliceViews`, so generated bindings and tools can ask for the semantic bucket they need without copying catalog scan logic. Live feeds compose several query surfaces into one client-facing snapshot without making the UI own refresh loops: ```csharp var viewportFeed = CultMesh.LiveFeed( "aetheria.rts.viewport.feed", (request, context) => SnapshotViewportAsync(request, context), (request, context) => WatchViewport(request, context), new[] { CultMesh.ProjectionSource("daemon:aetheria.frame.latest.v1"), CultMesh.ProjectionSource("daemon:aetheria.health.latest.v1") }, new CultMeshRouteHint(CultMeshLocalityKind.SharedMemory)); var feedDiagnostics = CultMesh.DescribeLiveFeed(viewportFeed); ``` When a runtime has a snapshot path before it has native reactive transport, `CultMesh.PollingQueryWatcher(...)` provides a disposable watch adapter: ```csharp var feed = CultMesh.LiveFeed( "aetheria.rts.viewport.feed", SnapshotViewportAsync, CultMesh.PollingQueryWatcher( SnapshotViewportAsync, new CultMeshPollingWatchOptions( TimeSpan.FromMilliseconds(50)))); ``` The polling adapter is intentionally a bridge primitive: application UI code still receives a typed `Watch(...)` handle, and the sampling loop can later be replaced by shared-memory, IPC, network, or WASM-native reactivity without changing renderer call sites. The staged roadmap for growing these handles into the cross-runtime developer experience lives in `docs/cross-runtime-primitives-roadmap.md`. When a project discovers a reusable state-ref, operation, query, projection, authority, watch, surface-binding, schema-generation, routing, diagnostic, or native-slab abstraction, it should graduate into that roadmap and then into the shared CultMesh/CultLib layer instead of remaining a private bridge. ### RUDP Helpers `CultMesh.ParseRudpEndpoint(...)`, `CreateRudpServer(...)`, `CreateRudpClient(...)`, `CreateRudpClientForPeer(...)`, and `CreateRudpClientForAuthorizedPeer(...)` provide the branded CultMesh path to the native CultNet RUDP socket transport. `ConnectRudpClient(...)`, `ConnectRudpClientForPeer(...)`, and `ConnectRudpClientForAuthorizedPeer(...)` also perform the client handshake before returning the same transport. These helpers parse endpoint contact hints and choose authorized peers; `GameCult.Networking` still owns the RUDP packet codec, session state, resend, fragmentation, and channel semantics. ### Shard Authority Each shard has one primary writer for now. Non-primary writes are rejected or explicitly forwarded. Stale epochs fail loudly. ### Reactive Documents Consumers subscribe to typed document changes through `CultNetDatabase` watch methods. Subscriptions receive domain changes rather than storage envelopes. ### Client Prediction `CultNetClientAuthorityScope` declares input documents a runtime may predict. `PutPredictedAsync` writes local state and emits `Predicted`. When the authoritative log arrives, the database emits `Reconciled`. ### Replica Catch-Up Shard logs can be requested over schema-v0 and applied by replicas. Replica cursors can be stored with `ICultNetShardReplicaCursorStore`. Authoritative shard logs can be persisted with `ICultNetShardMutationLogStore`; the file implementation stores one MessagePack log per shard so catch-up survives a primary restart. Compacted history returns an explicit resync requirement so a replica can fall back to a shard-bounded snapshot before applying newer log entries. Applying that snapshot replaces the local shard view and advances the replica cursor to the snapshot's represented log sequence. ### Simulation Witness Consensus `CultNetSimulationObservation` records what a node saw for a simulation fact. `CultNetSimulationObservationHub` collects those observations and emits `CultNetSimulationConsensusCandidate` updates. Candidates are opinions. `CultMeshSimulationFactCommitter` commits quorum candidates as `CultMeshSimulationFact` documents through `CultNetDatabase`, so final world state still belongs in the authoritative shard log. `CultMeshGameSession` is the gameplay-facing composition layer. It owns the common loop for prediction, observations, candidate watches, simulation fact watches, and committing new quorum facts without forcing game code to manually wire every bridge.