# CultMesh Kotlin Kotlin/JVM and Android client substrate for CultCache, CultNet, and CultMesh. It provides typed MessagePack document codecs, a channel-aware WebSocket CultNet transport, a single-peer CultNet RUDP socket transport, stream catalog negotiation, an in-memory CultCache, and the first Eve dashboard/sensor document contracts. The branded entrypoint mirrors C#/TypeScript/Python: ```kotlin val node = CultMesh.startNode() val verses = CultMesh.createVerseCatalog() val peers = CultMesh.createPeerCatalog() val leases = CultMesh.createAuthorityLeaseCatalog() val streams = CultMesh.createStreamCatalog() val schemas = CultMesh.createSchemaCatalog() val builtIns = CultMesh.createBuiltInSchemaCatalog(kinds = listOf("shared_contract")) val shards = CultMesh.createShardCatalog() ``` ## CultCache Happy Path Kotlin keeps the cache small but typed: document definitions wrap codecs, records are stored as encoded payload bytes, and callers work through typed helpers: ```kotlin val notes = stringDocument("kotlin.note", "kotlin.note.v1") val cache = CultCache() cache.put(notes, "note:1", "hello") val note = cache.getRequired(notes, "note:1") val handle = cache.document(notes, "note:2") handle.put("second") val allNotes = cache.getAll(notes) cache.delete(notes, "note:1") ``` `CultMeshNode` exposes the same typed cache surface through `remember`, `recall`, `require`, and `forget`. This is not the C# SoA store; it is the Kotlin client/runtime cache shape needed for feature and ergonomic parity without pretending Android wants Unity's hot-loop memory layout. Raw snapshot sync uses the same schema-v0 MessagePack documents as the other runtimes: ```kotlin val notes = stringDocument("kotlin.note", "kotlin.note.v1") val source = CultMeshNode() val target = CultMeshNode() source.cache.register(notes) target.cache.register(notes) source.remember(notes, "note:1", "hello") val request = cultNetSnapshotRequest( messageId = "sync-notes", schemaIds = listOf(notes.schemaVersion), ) val response = source.createRawSnapshotResponse(request) target.applyRawSnapshotResponse(response) val note = target.require(notes, "note:1") ``` When the caller wants one record as a local typed view, `syncDocument(...)` applies just that snapshot record and returns the requested document type. This is the comfortable alias path: the source can publish one Kotlin type, while the target registers a different Kotlin type with the same schema version. ```kotlin val sourceNote = cultDocument(SourceNoteCodec) val uiNote = cultDocument(UiNoteCodec) // same schemaVersion as sourceNote source.remember(sourceNote, "note:bridge", SourceNote("kotlin.note.v1", "hello")) val response = source.createRawSnapshotResponse( cultNetSnapshotRequest( messageId = "sync-ui-note", schemaIds = listOf(uiNote.schemaVersion), recordKeys = listOf("note:bridge"), ), ) val note: UiNote = target.syncDocument(response, uiNote, "note:bridge") ``` `applyRawDocumentPut(...)`, `applyRawSnapshotResponse(...)`, and `applyDocumentDelete(...)` require matching codecs to be registered first, so raw bytes re-enter the typed cache through the same document definitions that local Kotlin callers use. Reactive document handles let Kotlin callers keep a typed local view and have CultMesh flush changed state on the debounce cadence: ```kotlin val note = CultMesh.reactiveDocument( target, uiNote, "note:bridge", CultReactiveDocumentOptions(flushDelayMs = 16), ) note.current.body = "local prediction" ``` For immutable document types, use `update { it.copy(...) }` or `setCurrent(...)`. When an authoritative raw document put arrives while local state is dirty, `applyRawDocumentPut(...)` records a `CultReactiveDocumentReconciliation` with the canonical value, predicted value, and a delta. Tuple-backed MessagePack codecs report delta keys by field slot, such as `"0"` and `"1"`. ## WebSocket Transport For browser/mobile-friendly schema lanes, `CultNetWebSocketTransportConnection` wraps the tiny WebSocket client behind the same transport-frame shape used by the other runtimes: ```kotlin val transport = CultMesh.startNode().connectTransport(URI("ws://127.0.0.1:3075/mesh")) transport.sendSchema(cultNetSchemaCatalogRequest(messageId = "schemas").toBytes()) val frame = transport.receive() check(frame?.channelId == "schema") // Or stay at the schema-message level. transport.sendSchemaMessage(cultNetSchemaCatalogRequest(messageId = "schemas")) val message = transport.receiveSchemaMessage() check(message?.schemaVersion == "cultnet.schema_catalog_response.v0") // Or let the transport perform the standard request/response/apply cycle. val schemas = CultMesh.createSchemaCatalog() transport.syncSchemaCatalog( schemas, messageId = "schemas", includeSchemaJson = true, kinds = listOf("document_payload"), ) ``` The WebSocket adapter advertises a `websocket` transport profile with one reliable ordered `schema` channel and exposes transfer stats. `sendSchema`, `sendSchemaMessage`, `receiveSchema`, and `receiveSchemaMessage` keep the schema lane at the same ergonomic level as RUDP. WebSocket and RUDP both implement `CultNetSchemaMessageTransport`, so `fetchSchemaCatalog`, `syncSchemaCatalog`, `fetchShardCatalog`, and `syncShardCatalog` are shared schema-message transport helpers rather than duplicated adapter opinions. The catalogs still own imported state; the transport only performs the standard request/response hop. WebSocket is the stream adapter; RUDP remains the portable realtime UDP path. Schema catalogs are also first-class, so Kotlin peers can publish and consume descriptor responses instead of hand-assembling maps: ```kotlin val catalog = CultNetSchemaCatalog() catalog.upsert( defineCultNetSchemaDescriptor( schemaId = "kotlin.note.v1", kind = "document_payload", documentType = "kotlin.note", title = "Kotlin Note", schemaJson = """{"type":"object","properties":{"body":{"type":"string"}}}""", ), ) val response = catalog.createResponse( cultNetSchemaCatalogRequest( messageId = "schema-catalog", includeSchemaJson = true, kinds = listOf("document_payload"), ), ) ``` `CultNetSchemaCatalog.applyResponse(...)` imports `cultnet.schema_catalog_response.v0` descriptors from other runtimes and keeps their content hashes, wire contracts, schema ids, and optional schema JSON. `CultMesh.createBuiltInSchemaCatalog(...)` returns the Kotlin-supported CultNet/CultMesh descriptors on the same catalog surface, with optional `schemaIds`, `kinds`, and inline-schema filters. It includes schema catalog, shard catalog, shard log, Verse catalog, peer exchange, and the shared transport profile contract. Descriptors for shared schema files keep the canonical schema ids and content hashes; Kotlin-local descriptor bodies use schema-version ids until shared schema files exist. Inline schema JSON is opt-in and only emitted for descriptor bodies Kotlin owns. Shard catalogs and shard-log responses use the same schema-v0 lane: ```kotlin val shards = CultNetShardCatalog() shards.upsert( CultNetShardDescriptor( shardId = "notes-a", ownerRuntimeId = "kotlin-owner", epoch = 7, isPrimary = true, schemaIds = listOf(notes.schemaVersion), keyPrefix = "note:", primaryEndpoints = listOf("rudp://127.0.0.1:5000"), ), ) val shardResponse = shards.createResponse( cultNetShardCatalogRequest( messageId = "discover-shards", schemaIds = listOf(notes.schemaVersion), recordKeys = listOf("note:1"), ), ) val logRequest = cultNetShardLogRequest( messageId = "pull-notes", shardId = "notes-a", shardEpoch = 7, afterSequence = 12, ) ``` `CultCache.applyShardLogResponse(...)` applies `added` and `updated` entries through raw document put messages and `removed` entries through document delete messages. `CultNetInMemoryShardReplicaCursorStore` keeps the last applied sequence for lightweight Kotlin clients. ## RUDP Happy Path Kotlin exposes factory helpers around the shared RUDP transport so callers can write client/server code without hand-binding sockets or repeating channel strings: ```kotlin CultMesh.createRudpServer( runtimeId = "kotlin-server", connectionId = 0x10203040, tuning = CultNetRudpSocketTuning(maxFragmentBytes = 1024), ).use { server -> val peer = CultMeshPeerCard( peerId = "kotlin-server", verseId = "local", endpoints = listOf("rudp://127.0.0.1:${server.localPort}"), roles = listOf("schema"), ) CultMesh.createRudpClientForPeer( runtimeId = "kotlin-client", connectionId = 0x10203040, peer = peer, ).use { client -> client.connect("join") check(pumpRudpPairUntilConnected(client, server)) client.sendSchema("client-state") val payload = server.receiveSchema(timeoutMs = 1_000) val remoteSchemas = CultMesh.createSchemaCatalog() client.syncSchemaCatalog( remoteSchemas, messageId = "rudp-schemas", kinds = listOf("document_payload"), ) } } ``` When peer discovery and authority leases are already local, callers can ask the branded entrypoint to select an authorized RUDP peer for a Verse role: ```kotlin val peers = CultMesh.createPeerCatalog() val leases = CultMesh.createAuthorityLeaseCatalog() val client = CultMesh.connectRudpClientForAuthorizedPeer( runtimeId = "kotlin-client", connectionId = 0x10203040, peers = peers, leases = leases, verseId = "local", role = "schema", connectPayload = "join".toByteArray(), ) ``` The helper uses `CultMeshPeerCatalog.firstAuthorized(...)`, which delegates trust to `CultMeshAuthorityLeaseCatalog.isAuthorized(...)`; peer endpoints remain contact hints, not authority. The connected helper delegates to the same `CultNetRudpSocketTransportConnection` after authorized peer selection and handshake. The lower-level `createRudpClient...` helpers remain available when a caller intentionally owns the handshake or in-process polling loop. The sugar delegates to the same transport and `cultnet.transport.rudp.v0` packet codec used by the cross-runtime interop harness. `sendSchema`, `sendLatest`, and `sendRealtime` select the shared channel semantics; they do not create a Kotlin-only dialect. For two same-process transports, use `pumpRudpPairUntilConnected(...)` or an explicit server pump to drive both sides through the handshake. Because RUDP also implements `CultNetSchemaMessageTransport`, it uses the same catalog helpers as WebSocket, with timeout-aware receive loops: `fetchSchemaCatalog`, `fetchSchemaDescriptors`, `syncSchemaCatalog`, `fetchShardCatalog`, `fetchShardDescriptors`, and `syncShardCatalog`. For lower-level code, `CultMesh.parseRudpEndpoint("rudp://127.0.0.1:4100")` returns the host/port pair, and `CultMesh.createRudpClient(...)` accepts either that parsed endpoint or the endpoint string directly. Kotlin also exposes the shared reconnect-policy helper for peers that need a portable backoff document without inventing a JVM-only delay dialect: ```kotlin val policy = createReconnectPolicy(policyId = "rudp-default", maxAttempts = 8) val nextDelayMs = computeReconnectDelayMs(policy, attempt = 3, jitterMs = 17) ``` The helper publishes `cultnet.reconnect_policy.v0`, matches the C#, TypeScript, Rust, and Python defaults, and is advertised by Kotlin RUDP transport profiles as `reconnectPolicy`. `CultNetRudpReconnectLoop` consumes the same controller for caller-owned RUDP client factories: the receive loop decides when a transport is closed, then the reconnect loop schedules the next attempt and opens a fresh transport through the supplied factory. `EveDashboardStateDocument` mirrors the CultUI-shaped dashboard surface contract: `surface.root` is the retained UI tree, `surface.assets` carries cacheable media references, and the flat `nodes` projection remains a compatibility and binding surface for selection, commands, and fallback rendering. ## Discovery Catalogs Kotlin can model and exchange the same CultMesh discovery documents as the other runtimes: ```kotlin val verses = CultMeshVerseCatalog() verses.upsert( CultMeshVerseDescriptor( verseId = "public", displayName = "Public Verse", authorityModel = "federated", compatibility = CultMeshVerseCompatibility( transportVersion = "cultmesh.v0", rulesHash = "rules-a", ), discoveryEndpoints = listOf("rudp://127.0.0.1:4000"), ), ) val response = verses.createResponse( cultMeshVerseCatalogRequest( messageId = "discover-verses", transportVersion = "cultmesh.v0", ), ) val peers = CultMeshPeerCatalog() peers.upsert( CultMeshPeerCard( peerId = "kotlin-peer", verseId = "public", endpoints = listOf("rudp://127.0.0.1:4100"), roles = listOf("read-replica", "schema"), ), ) val peerResponse = peers.createResponse( cultMeshPeerExchangeRequest( messageId = "discover-peers", verseId = "public", roles = listOf("schema"), ), ) ``` `createResponse(...)` and `applyResponse(...)` operate on `CultNetMessage` instances, so catalog discovery can ride the same MessagePack schema-v0 lane as RUDP schema traffic. Peer cards are contact hints, not trust. Kotlin now mirrors the C#/TS/Python lease gate so local clients can keep discovery and authority separate: ```kotlin val peer = CultMeshPeerCard( peerId = "kotlin-peer", verseId = "public", endpoints = listOf("rudp://127.0.0.1:4100"), roles = listOf("shard-primary"), shardIds = listOf("players"), authorityLeaseId = "lease:kotlin-peer", ) val leases = CultMesh.createAuthorityLeaseCatalog() val unsubscribeLeaseWatch = leases.watch { lease -> println("authority lease changed: ${lease.leaseId}") } leases.upsert( CultMeshAuthorityLease( leaseId = "lease:kotlin-peer", verseId = "public", peerId = "kotlin-peer", roles = listOf("shard-primary"), shardIds = listOf("players"), issuerRuntimeId = "odin", validFrom = Instant.parse("2026-06-15T00:00:00Z"), expiresAt = Instant.parse("2026-06-15T01:00:00Z"), ), ) check(leases.isAuthorized(peer, "shard-primary", "players")) unsubscribeLeaseWatch() ``` ## Streaming Catalog Kotlin also mirrors the CultMesh stream declaration and negotiation surface for Android-adjacent media, sensor, tensor, and byte streams. The catalog owns stream identity, clock metadata, body transport negotiation, and latest-frame cursors; it does not own the frame bytes themselves. ```kotlin val streams = CultMesh.createStreamCatalog() val unsubscribeStreamWatch = streams.watch { stream -> println("stream declared: ${stream.streamId}") } val unsubscribeFrameWatch = streams.watchFrames { frame -> println("latest frame ${frame.sequence} for ${frame.streamId}") } streams.declare( CultMeshStreamDescriptor( streamId = "mimir:camera", verseId = "studio", ownerPeerId = "android-device", kind = CultMeshStreamKinds.Video, clock = CultMeshStreamClock("android-elapsed-realtime"), video = CultMeshVideoStreamFormat( width = 1920, height = 1080, pixelFormat = "rgba8", framesPerSecond = 60.0, ), preferredTransports = listOf( CultMeshStreamBodyTransports.AHardwareBuffer, CultMeshStreamBodyTransports.SharedMemory, CultMeshStreamBodyTransports.CultCachePage, ), ), ) val lane = streams.negotiate( "mimir:camera", CultMeshStreamConsumerProfile( peerId = "fensalir", verseId = "studio", supportedTransports = listOf(CultMeshStreamBodyTransports.AHardwareBuffer), acceptedKinds = listOf(CultMeshStreamKinds.Video), maxInFlightFrames = 2, ), ) unsubscribeStreamWatch() unsubscribeFrameWatch() ``` `EveMediaObservationDocument` carries byte-backed device streams such as camera luma frames and microphone PCM blocks. The document is observation transport, not synchronization authority: the device owns capture and local timestamps, while Mimir or another consumer owns alignment and interpretation. ## Build ```powershell powershell -ExecutionPolicy Bypass -File .\packages\cultmesh-kotlin\build.ps1 ``` The build writes `artifacts/cultmesh-kotlin/cultmesh-kotlin.jar`. It also runs the built-in RUDP packet fixture and localhost UDP socket self-test.