476 lines
16 KiB
Markdown
476 lines
16 KiB
Markdown
# 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.
|