2026-06-14 20:32:25 +01:00
# CultNet Transport Parity Map
CultNet payload parity is not enough. The runtimes can already trade schema-v0
2026-06-16 01:07:17 +01:00
MessagePack documents through the interop lane, and the shared
`cultnet.transport.rudp.v0` packet/session language now exists across C#,
TypeScript, Rust, Python, and Kotlin. The remaining split is service adoption:
C# still carries the production LiteNetLib path, and older TCP-framed or
WebSocket-like bodies still exist for local services and harnesses.
2026-06-14 20:32:25 +01:00
This document is the working map for promoting transport into CultNet itself so
C#, TypeScript, Rust, Python, Kotlin, and future runtimes can speak the same
2026-06-16 01:07:17 +01:00
network language. Runtime role boundaries live in
[runtime-parity-scope.md ](runtime-parity-scope.md ).
2026-06-14 20:32:25 +01:00
## Objective
CultNet owns cross-runtime transport semantics:
- peers discover each other without runtime-specific side channels;
- connection/session lifecycle is described the same way in every runtime;
- reliable ordered delivery is portable and testable across runtimes;
- unreliable and sequenced realtime channels can exist beside reliable state
sync without changing payload contracts;
- LiteNetLib becomes one adapter, not the hidden specification.
## Current Mechanism
| Runtime | Current data transport | Discovery | Transport authority today |
| --- | --- | --- | --- |
2026-06-16 07:30:56 +01:00
| C# `GameCult.Networking` | LiteNetLib UDP `NetManager` / `NetPeer` ; sends legacy union messages and schema-v0 messages with `DeliveryMethod.ReliableOrdered` ; single-peer RUDP socket transport exists in the library | LiteNetLib connection requests and app-level peer/catalog surfaces | Production LiteNetLib adapter profile plus UDP socket binding for the shared RUDP reliability owner |
2026-06-17 11:22:17 +01:00
| C# interop peer | Schema-v0 MessagePack over TCP-framed or shared RUDP transport | UDP multicast probe/announce with TCP and RUDP transport profiles | Test harness transport parity |
2026-06-14 23:03:29 +01:00
| TypeScript `cultnet-ts` | `CultNetPeer` over any Node `Duplex` , TCP-framed transport, or single-peer RUDP socket transport; interop uses TCP | UDP multicast probe/announce in the interop peer | First UDP socket binding for the shared RUDP reliability owner |
2026-06-17 10:07:37 +01:00
| Rust `cultnet-rs` | Interop example serves and dials schema-v0 MessagePack over TCP-framed or shared RUDP transport; single-peer RUDP socket transport exists in the library | UDP multicast probe/announce with TCP and RUDP transport profiles | UDP socket binding for the shared RUDP reliability owner |
Split the Python runtime into cultcache-py, cultnet-py, cultmesh-py
One distribution named cultcache-py carried three libraries. Rust and
TypeScript layer them as cultcache < cultnet < cultmesh; Python now does
the same, one package per layer, module names unchanged so every
`from cultmesh_py import ...` keeps working.
Two imports ran against that layering and are resolved by moving code to
where the dependency direction says it lives, not by adding a shim:
- cultnet_py.interop_peer imported the Verse/peer catalog, authority
lease, stream, and simulation-fact contracts from cultmesh_py. They are
wire contracts a bare peer has to speak without owning a node, which is
why cultnet-rs and cultnet-ts keep them in the net layer. They now live
in cultnet_py.cultmesh_contracts; cultmesh_py re-exports them.
- cultcache_py.benchmark imported cultnet_py. It measures framed CultNet
parse beside cache paths, so it and compare_csharp move to cultnet_py.
verify checks all three packages and moves to cultmesh_py.
The single 6,693-line test module is split by what each test touches: a
test using any cultmesh_py name lands in cultmesh-py, else cultnet_py in
cultnet-py, else cultcache-py. Each suite runs with only its layer and the
layers below on the path, so a test that reaches up fails to import
rather than quietly binding the packages back together. 11 / 53 / 78 =
the same 142.
Workflows install all three; the publish job is one matrix over the
three packages keyed by tag prefix. The TS test harnesses put all three
src directories on PYTHONPATH. cultcache-py bumps to 0.2.0 because it no
longer contains cultnet_py or cultmesh_py; the new packages start at
0.1.0. Nothing was ever published, so no PyPI consumer moves.
cultcache-py 11 tests, path: cultcache-py/src
cultnet-py 53 tests, path: + cultnet-py/src
cultmesh-py 78 tests, path: + cultmesh-py/src
python -m cultmesh_py.verify -> ok, all five checks
cultnet_py.interop_peer imports with cultmesh_py absent
Not run here: the cultnet-ts interop ring and cultcache-ts store matrix
need dotnet/kotlin peers; their PYTHONPATH change is four lines.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-10 13:10:47 +02:00
| Python `cultnet-py` | TCP sockets with 4-byte length-prefixed MessagePack frames for local CultMesh/CultNet server and client; single-peer RUDP socket transport exists in the library | Endpoint lists and CultMesh peer/Verse catalogs | UDP socket binding for the shared RUDP reliability owner |
2026-06-17 12:45:30 +01:00
| Kotlin `cultmesh-kotlin` | Channel-aware WebSocket transport connection for reliable ordered `schema` frames; single-peer RUDP socket transport exists in the library; interop CLI serves and dials schema-v0 MessagePack over TCP-framed or shared RUDP transport | CultMesh Verse and peer catalogs, plus endpoint lists carried in schema-v0 catalog messages | WebSocket/TCP adapters plus UDP socket binding for the shared RUDP reliability owner, with build-script and TypeScript harness proof |
2026-06-14 20:32:25 +01:00
2026-06-16 00:06:56 +01:00
The live split is therefore: payload language and the native RUDP packet/session
language now converge across the targeted runtimes, while production service
adoption still varies by runtime and older TCP/LiteNetLib/WebSocket bodies have
not all been lowered behind the shared transport port.
2026-06-14 20:32:25 +01:00
## Invariants
- `cultnet.schema.v0` payloads are transport-neutral. Message schemas must not
know whether they rode TCP, LiteNetLib, WebSocket, or CultNet reliable UDP.
- Discovery is its own concern. A discovery packet may advertise transport
endpoints and capabilities, but it does not own reliable delivery semantics.
- The first portable realtime channel must provide reliable ordered delivery,
because schema catalogs, snapshots, shard logs, auth/session messages, and
mutation forwarding already depend on ordered request/response behavior.
- Transport capability negotiation must happen before higher-level CultMesh
state claims a peer is usable for realtime work.
- Auth/session primitives bind to a connection, but credential encryption and
session token formats remain owned by CultNet security, not by UDP packet
framing.
- Backpressure, resend pressure, MTU limits, fragmentation, ping/timeout, and
reconnect posture are transport-owned signals. They must not leak upward as
ad hoc message-level retry loops.
## Intended Ownership
`cultnet.transport.v0` owns the transport contract:
- endpoint description: protocol, host, port, path/group when relevant;
- channel descriptions: reliable ordered, reliable unordered, sequenced, and
unreliable;
- packet envelope: connection id, sequence/ack state, channel id, fragment id,
payload encoding, and payload bytes;
- session lifecycle: connect, accept/reject, disconnect reason, timeout, ping,
reconnect state, and feature negotiation;
- flow control: send queue limits, resend window, fragmentation limit, and
backpressure reporting.
Adapters own socket mechanics:
- `cultnet.transport.tcp_framed.v0` : existing 4-byte length-prefixed MessagePack
stream, reliable ordered only;
- `cultnet.transport.litenetlib.v0` : C# adapter preserving current
`GameCult.Networking` behavior while exposing CultNet channel semantics;
- `cultnet.transport.websocket.v0` : browser/mobile-friendly stream adapter,
reliable ordered only;
- `cultnet.transport.rudp.v0` : native cross-runtime reliable UDP transport,
replacing LiteNetLib as the portable realtime specification.
Payload handlers own documents:
- `cultnet.login.v0` , `cultnet.register.v0` , `cultnet.verify.v0` , and
`cultnet.login_success.v0` are security/session messages;
- `cultnet.schema_catalog_*` , snapshot, shard catalog, shard log, subscription,
and simulation messages remain schema-v0 payloads;
- no payload handler decides packet resend, channel ordering, or fragmentation.
## Cut Line
- Do not build a Python-only LiteNetLib clone.
- Do not let the TCP interop harness become the implied production transport.
- Do not hide transport capability in loose endpoint strings.
- Do not add message-level retry compensators for missing reliable UDP.
- Do not put UDP packet mechanics into CultMesh database/session code.
- Do not treat C# LiteNetLib behavior as optional folklore; mine it for the
required semantics, then express those semantics in CultNet-owned contracts.
## First Portable Contract
The first shippable slice should be a transport profile document that every
runtime can advertise through schema catalogs and hello/peer descriptors:
```text
cultnet.transport_profile.v0
runtimeId
transports[]
transportId
protocol
endpoint
wireContracts[]
channels[]
channelId
delivery
ordering
maxPayloadBytes
maxFragmentBytes
```
This is not the reliable UDP implementation. It is the shared language that
lets the runtimes stop guessing what kind of pipe a peer is offering.
## Implementation Sequence
2026-06-16 01:07:17 +01:00
1. Add `cultnet.transport_profile.v0` as a shared contract in C#, TS, Rust,
Python, and Kotlin catalogs.
2026-06-14 20:32:25 +01:00
2. Make every runtime advertise its current transport honestly:
`tcp_framed` , `litenetlib` , or `websocket` .
3. Add a cross-runtime transport-profile interop check so parody surfaces fail
loudly.
4. Introduce a narrow transport port in each runtime:
`connect` , `accept` , `send(channel, payload)` , `receive` , `close` , `stats` .
5. Put current TCP/LiteNetLib/WebSocket bodies behind that port.
6. Build `cultnet.transport.rudp.v0` once against the shared port and prove it
2026-06-16 01:07:17 +01:00
with C#/TS/Rust/Python/Kotlin ping, loss, reordering, fragmentation,
reconnect, and schema-message tests.
2026-06-14 20:32:25 +01:00
2026-06-14 21:28:23 +01:00
Current progress:
2026-06-16 01:07:17 +01:00
- Steps 1-3 are live in C#, TypeScript, Rust, Python, and Kotlin.
2026-06-14 21:59:09 +01:00
- C# now has the shared `tcp_framed` transport profile helper plus a
`TcpFramedTransportConnection` with schema-channel `SendAsync` ,
`ReceiveAsync` , and transfer stats. The C# interop peer advertises and uses
2026-06-17 11:22:17 +01:00
that shared port instead of owning raw TCP frame I/O directly. The C# interop
peer now also advertises and serves the full schema-v0 flow over
`interop-rudp` , and its dial path can use the shared RUDP transport while
keeping TCP-framed as compatibility.
2026-06-16 07:30:56 +01:00
- C# now has a `litenetlib` transport profile helper, and the production
`Client` /`Server` expose profiles for the LiteNetLib lane. The profile names
both the modern reliable ordered `schema` channel and the legacy reliable
ordered `legacy` union-message channel, so LiteNetLib is described as an
2026-06-16 07:41:29 +01:00
adapter instead of remaining the hidden default. `NetPeer` send helpers now
2026-06-16 11:15:41 +01:00
route through `LiteNetLibTransportConnection` ; `Client` and `Server` now keep
a per-peer adapter and route their own schema/legacy sends through it as
well. Inbound payload classification and transfer stats also belong to that
2026-06-16 11:29:15 +01:00
channel-aware adapter before dispatching schema-v0 or legacy messages. The
C# database, simulation-observation, Verse-discovery, and peer-exchange
2026-06-16 11:54:54 +01:00
service wrappers now enter their built-in handlers through
`CultNetServerPeer` , a transport-aware server peer context. Responses send
through that context instead of reaching around the per-peer adapter with
2026-06-17 13:27:56 +01:00
direct `NetPeer` extension sends. The C# schema-client port now also has an
RUDP adapter; shard log fetch, shard snapshot fetch, and shard write
forwarding select it for `rudp://` primary endpoints and keep LiteNetLib for
`cultnet://` endpoints, so those service clients no longer need custom
injection to leave the LiteNetLib lane.
2026-06-14 21:28:23 +01:00
- TypeScript has the first narrow transport connection port:
`TcpFramedTransportConnection` owns length-prefixed frame delivery, exposes
frame/close/error events, `send(channel, payload)` , `close` , and transfer
2026-06-16 09:51:00 +01:00
stats, and destroys its owned stream on close. `CultNetPeer` can still run
over either the compatibility `Duplex` stream path or the transport
connection path, while the TypeScript interop peer now accepts and dials TCP
peers through `TcpFramedTransportConnection` so the parity harness exercises
2026-06-16 12:15:23 +01:00
the shared port instead of raw socket framing. `createTcpFramedCultNetPeer`
gives application callers the same transport-first path without hand-building
the profile and adapter; raw `Duplex` peer construction is now explicitly the
compatibility lane.
2026-06-14 21:38:59 +01:00
- Python now has the same `tcp_framed` transport profile helper plus a
synchronous `TcpFramedTransportConnection` with `send` , `receive` , `close` ,
2026-06-16 04:11:24 +01:00
and stats. `CultNetRawClient` , database subscriptions, and the local
CultMesh server connection loop send/read through that port instead of owning
2026-06-16 10:33:55 +01:00
frame I/O directly. The Python TCP interop peer now also accepts and dials
through that port, so the parity harness no longer keeps a raw framing
side-channel for Python's schema lane.
2026-06-14 21:48:07 +01:00
- Rust now has the same `tcp_framed` transport profile helper plus a
`TcpFramedTransportConnection` with schema-channel `send` , `receive` , and
2026-06-17 10:07:37 +01:00
transfer stats. The Rust interop peer advertises TCP and RUDP profiles and
serves/dials schema-v0 through the shared RUDP path without giving RUDP its
own document semantics.
2026-06-16 07:14:31 +01:00
- Kotlin now has a `websocket` transport profile helper plus
`CultNetWebSocketTransportConnection` , which wraps the older binary
WebSocket client behind the same `CultNetTransportFrame` and stats shape for
2026-06-16 11:41:32 +01:00
reliable ordered `schema` frames. The adapter now also has `sendSchemaMessage`
and `receiveSchemaMessage` sugar so JVM callers can exchange schema-v0
MessagePack messages without hand-parsing transport frames.
2026-06-16 01:07:17 +01:00
- TypeScript, C#, Rust, Python, and Kotlin now share the first
2026-06-14 22:20:49 +01:00
`cultnet.transport.rudp.v0` packet codec fixture: the same reliable ordered
fragmented data packet encodes to the same bytes in every runtime. This is not
the RUDP runtime yet; it is the binary packet language the runtimes must
converge on before resend loops, windows, and timeout behavior are allowed to
claim parity.
2026-06-16 01:07:17 +01:00
- TypeScript, C#, Rust, Python, and Kotlin now share the first deterministic RUDP
2026-06-14 22:53:00 +01:00
reliability state machine: connect/accept handshake, packet-level
ack/ack-mask accounting, reliable resend scheduling, duplicate suppression,
and reliable ordered channel delivery. It is in-memory and socket-free so the
behavior can be tested before any runtime binds it to UDP I/O.
2026-06-14 23:47:55 +01:00
- C#, TypeScript, Rust, Python, and Kotlin now have socket-backed RUDP transport
2026-06-14 23:18:08 +01:00
connections that bind a single UDP peer to the shared RUDP session. TypeScript
emits the same `frame` events as the TCP-framed transport and can carry
2026-06-14 23:32:24 +01:00
`CultNetPeer` schema messages over reliable ordered `schema` frames; C#,
2026-06-14 23:47:55 +01:00
Rust, Python, and Kotlin expose the same transport frame/stats shape through
2026-06-14 23:32:24 +01:00
synchronous socket polling.
2026-06-15 00:29:09 +01:00
- The TypeScript interop harness now proves bidirectional cross-runtime RUDP
2026-06-15 01:17:08 +01:00
socket exchange with C#, Kotlin, Python, and Rust: TypeScript can dial those
UDP peers, C#/Kotlin/Python/Rust can dial a TypeScript UDP peer, and all sides
exchange reliable ordered `schema` frames through the shared handshake and
packet language.
2026-06-16 01:42:02 +01:00
- The same harness now proves schema-v0 MessagePack messages over RUDP in both
2026-06-16 02:23:02 +01:00
directions for C#, Kotlin, Python, and Rust peers against TypeScript. Those tests
2026-06-16 01:42:02 +01:00
send `cultnet.schema_catalog_request.v0` payloads through reliable ordered
`schema` frames and validate `cultnet.hello.v0` responses with advertised
2026-06-16 04:22:19 +01:00
RUDP transport profiles where the responding runtime owns them, including the
shared `reconnectPolicy` field.
2026-06-15 01:27:23 +01:00
- The same harness now proves reliable ordered `schema` delivery survives one
2026-06-15 01:40:43 +01:00
dropped data packet in both directions between TypeScript and C#/Kotlin/Python/Rust .
The drops happen below the transport connection through a UDP bridge, so the
recovery is RUDP resend/ack behavior, not application-level retry.
2026-06-15 02:52:01 +01:00
- The same harness now proves reliable ordered `schema` delivery survives
reordered data packets in both directions between TypeScript and
C#/Kotlin/Python/Rust . The bridge delays one packet below the transport, sends
the following packet first, and then releases the held packet; delivered frames
still surface in sequence.
2026-06-16 13:18:39 +01:00
- C#, TypeScript, Rust, Python, and Kotlin now also guard against control-packet
sequence bleed in ordered channels: a received `ack` /control packet may
advance the global acknowledgement window, but it must not block the next
ordered `schema` frame for that channel. Runtime-local RUDP tests prove the
data-control-data sequence in each implementation.
2026-06-15 02:26:34 +01:00
- TypeScript, C#, Rust, Python, and Kotlin now share the first RUDP
fragmentation implementation: the session can split oversized reliable
ordered payloads into fragment packets, reassemble them before delivery, and
the socket transport can carry fragmented `schema` frames when
`maxFragmentBytes` is configured.
- The TypeScript interop harness now proves fragmented reliable ordered
`schema` frames in both request and response direction between TypeScript and
C#/Kotlin/Python/Rust one-shot UDP peers.
2026-06-15 03:11:46 +01:00
- TypeScript, C#, Rust, Python, and Kotlin now share a transport-level RUDP
disconnect primitive: sessions create and consume `disconnect` packets with
raw reason bytes, socket transports surface the remote reason, and the
TypeScript interop harness proves reason propagation from C#/Kotlin/Python/Rust
one-shot UDP peers.
2026-06-15 03:26:40 +01:00
- TypeScript, C#, Rust, Python, and Kotlin now share transport-level ping/pong
and receive-timeout state: sessions create pings, answer pings with pongs,
expose pong payloads, and mark themselves disconnected after a configured
silent receive window. The TypeScript interop harness proves ping/pong payload
echo against C#/Kotlin/Python/Rust UDP peers; local runtime tests prove timeout
state transitions.
2026-06-15 15:24:11 +01:00
- TypeScript, C#, Rust, Python, and Kotlin now share bounded reliable-send
2026-08-23 18:54:18 +02:00
backpressure for RUDP sessions. At most 32 reliable packets are admitted to
2026-08-23 19:15:22 +02:00
the wire at once; later fragments remain in a session-owned FIFO and
acknowledgements promote the next packets. Receivers emit a cumulative ACK
for packets inside the 32-sequence ACK horizon and an exact ACK for an older
retransmit, so unrelated unreliable traffic cannot strand reliable work.
This keeps the send frontier well
2026-08-23 18:35:49 +02:00
inside the 4,096-sequence receive history instead of blasting an entire large
document and hoping the UDP buffers impersonate flow control.
`maxPendingReliablePackets` bounds both queued and in-flight packets before a
reliable frame is accepted. Socket transports expose an explicit reliable
flush where the runtime supports one, so callers that require confirmed
transport delivery do not substitute a fixed sleep. TCP-framed profiles do
not publish the field because they do not own the RUDP pending-reliable queue.
2026-09-30 00:55:14 +02:00
- The receive window is a contract, not a discovery. A receiver must hold 1,023
sequences and 4 MiB of payload beyond its contiguous received watermark, and
a conforming sender never exceeds either. The sender's flow window enforces
it without a wire field: a reliable packet is admitted only while its
sequence is at most 1,023 above the lowest unacked sequence and the payload
above that sequence stays within 4 MiB. The first packet is always
admissible, so a payload larger than 4 MiB goes out alone, and packets wait
in the FIFO in order, so a small packet never overtakes a large one. C#,
Rust, TypeScript, and Python enforce it; Kotlin does not yet.
2026-06-16 03:07:31 +01:00
- TypeScript, C#, Rust, Python, and Kotlin now share a portable
`cultnet.reconnect_policy.v0` document and deterministic exponential delay
2026-06-16 04:01:41 +01:00
helper, and RUDP transport profiles advertise that policy under
`reconnectPolicy` . This gives discovery the same policy language for
2026-06-16 05:29:45 +01:00
reconnect posture.
- TypeScript, C#, Rust, Python, and Kotlin now share a portable reconnect
controller shape over that policy: failed connection attempts produce the
same attempt number, delay, next-attempt time, exhaustion signal, and
successful-connection reset semantics. This is the orchestration primitive
service loops must use; it does not yet claim every production daemon or
socket path automatically redials through it.
2026-06-16 05:45:26 +01:00
- The C# LiteNetLib `Client` reconnect loop now consumes
`CultNetReconnectController` directly instead of owning a private attempt
counter and duplicate backoff constants. It still owns LiteNetLib socket
mechanics and UI-facing reconnect state; the controller owns retry attempt
scheduling.
2026-06-16 14:22:41 +01:00
- C# now has an `ICultNetSchemaClient` service-client port for schema-v0
2026-06-17 14:09:52 +01:00
request/response bodies. Verse discovery, peer exchange, shard-log fetch,
shard-snapshot fetch, and shard write forwarding clients consume the port and
choose the native RUDP schema client for `rudp://` endpoints while preserving
LiteNetLib for `cultnet://` endpoints. This moves transport choice below
service payload ownership without claiming every daemon uses native RUDP yet.
2026-06-16 06:54:42 +01:00
- C# now also has a poll-driven `CultNetRudpReconnectLoop` for the native RUDP
socket transport. Caller-owned game/service loops report closure, ask
`ReconnectIfDue(nowMs)` inside their own scheduler, and the shared controller
owns retry delay/exhaustion state while the caller-owned factory opens the
next `CultNetRudpSocketTransportConnection` .
2026-06-17 14:28:18 +01:00
- C# now has `CultNetRudpSocketTransportServer` , a multi-peer UDP listener that
demultiplexes remote endpoints into separate RUDP sessions and delivers
`(peer, frame)` records to higher service owners. This is the production
server substrate cut: UDP/session ownership is no longer limited to the
single-peer interop/client helper, but authentication and game-session
authority still remain above the transport.
2026-06-17 14:48:53 +01:00
- C# now also has `RudpCultNetSchemaServer` , a multi-peer schema-v0 service
host over that listener. Service code can register `OnCultNet<T>` handlers
and reply through `peer.SendCultNet(...)` without owning UDP demux or RUDP
session state. Database, Verse discovery, peer exchange, and simulation
bridges still need to adopt the shared schema-server peer port before the
old LiteNetLib `Server` bridge can be demoted.
2026-06-16 16:57:35 +01:00
- C# `GameCult.Mesh` now mirrors the branded RUDP facade shape used by
TypeScript, Python, Kotlin, and Rust: it parses `rudp://host:port` endpoints,
creates RUDP client/server transports from endpoint or peer-card contact
hints, and can create a RUDP client from the first peer authorized by the
2026-06-17 05:16:46 +01:00
authority lease catalog for a Verse role. The facade can also return a
connected RUDP client from a direct endpoint, peer card, or authorized peer
lookup, so schema-message helpers can ride the RUDP pipe without caller-side
handshake ceremony. RUDP packet/session behavior remains owned by
`GameCult.Networking` .
2026-06-16 05:58:28 +01:00
- TypeScript now has a `CultNetRudpReconnectLoop` that consumes the shared
controller while keeping socket construction caller-owned. A closed RUDP
transport schedules the next attempt with the portable policy, opens a fresh
caller-provided transport when the controller says it may retry, and resets
attempt state when the caller marks the connection established.
2026-06-16 06:28:22 +01:00
- Python now has the same `CultNetRudpReconnectLoop` shape for synchronous
callers: the caller-owned receive loop reports closure, the shared controller
owns retry delay/exhaustion state, and the caller-provided factory opens the
next `CultNetRudpSocketTransportConnection` .
2026-06-16 16:13:56 +01:00
- Python raw CultNet clients now consume a caller-provided
`CultNetSchemaTransport` factory for request/response and database
subscription flows. The default factory opens the existing TCP-framed schema
transport, but the raw client no longer owns inline socket setup as its
2026-06-16 23:37:59 +01:00
request truth. Python now also exposes `create_rudp_schema_transport(...)` ,
which handshakes a socket-backed RUDP client and gives `CultNetRawClient` the
same reliable ordered `schema` request path over `cultnet.transport.rudp.v0` ;
`CultMesh.create_client(endpoint="rudp://...")` is the branded ergonomic
helper for that path.
2026-06-16 16:31:13 +01:00
- Python's branded `CultMesh` facade now creates schema catalogs, built-in
schema catalogs, and shard catalogs by delegating to the existing
`cultnet_py` owners, matching the TypeScript/Kotlin/Rust entrypoint pattern
2026-06-16 16:42:03 +01:00
without creating a second catalog authority. The facade now also parses
`rudp://host:port` endpoints and creates RUDP client/server transports from
endpoint or peer-card contact hints while leaving packet/session semantics in
2026-06-16 16:52:20 +01:00
`cultnet_py` . Python peer catalogs also expose authorized-peer lookup, and
the branded facade can create a RUDP client from the first peer authorized by
2026-06-17 06:34:30 +01:00
the authority lease catalog for a Verse role. `CultMeshLocalServer` now also
starts a RUDP listener beside the TCP-framed listener by default and advertises
both transport profiles in `cultnet.hello.v0` ; the RUDP listener keeps schema
request handling in the same server authority while demultiplexing per-remote
2026-06-17 08:05:41 +01:00
`CultNetRudpSession` state. The Python interop peer now also serves and dials
schema-v0 over `interop-rudp` , advertises TCP-framed and RUDP in discovery and
hello, and caps interop RUDP schema frames into 1024-byte fragments so catalog
responses stay inside UDP datagram limits while remaining session-owned.
2026-06-16 06:43:22 +01:00
- Rust now has a poll-driven `CultNetRudpReconnectLoop` for substrate callers:
service loops report closure, ask `reconnect_if_due(now_ms)` inside their own
reactor, and the shared controller owns retry delay/exhaustion state while the
caller-owned factory opens the next socket transport.
2026-06-16 06:08:22 +01:00
- Kotlin now has the same RUDP reconnect-loop shape for JVM/Android callers:
the app-owned receive loop reports closure, `CultNetRudpReconnectLoop`
schedules retry through `CultNetReconnectController` , and the caller-provided
factory opens the next `CultNetRudpSocketTransportConnection` .
2026-06-16 00:17:35 +01:00
- Kotlin now mirrors the C#/TypeScript/Python local authority lease gate:
peer cards may advertise `authorityLeaseId` , but `CultMeshAuthorityLeaseCatalog`
owns role/shard/time authorization so discovery contact cannot impersonate
trust.
2026-06-16 00:27:16 +01:00
- TypeScript CultMesh local catalogs now expose the same practical discovery
ergonomics as the other runtimes: sorted local views, direct `get(...)`
lookup, unsubscribe-able `watch(...)` callbacks for Verse and peer catalogs,
2026-06-16 10:11:37 +01:00
watch callbacks for authority leases and stream declarations/frame cursors,
2026-06-16 16:18:08 +01:00
plus lease listing and lookup beside the authority check. The branded
`CultMesh` facade also creates schema catalogs, built-in schema catalogs, and
shard catalogs by delegating to the existing `cultnet-ts` owners, so callers
do not have to leave the CultMesh entrypoint for schema discovery or shard
2026-06-16 16:37:16 +01:00
topology. The facade now also parses `rudp://host:port` endpoints and creates
RUDP client/server transports from endpoint or peer-card contact hints while
2026-06-16 16:52:20 +01:00
leaving packet/session semantics in `cultnet-ts` . TypeScript now also mirrors
Kotlin's authorized-peer lookup and RUDP client helper, so peer cards remain
contact hints until the authority lease catalog authorizes the requested
2026-06-17 03:58:12 +01:00
Verse role. The facade can now also create a connected `CultNetPeer` from a
direct RUDP endpoint, peer card, or authorized peer lookup, so schema and shard
catalog request helpers ride the RUDP transport without callers hand-wrapping
2026-06-17 07:28:47 +01:00
the socket transport. The TypeScript interop peer now also serves and dials
the schema-v0 interop flow over `interop-rudp` while keeping TCP-framed as the
compatibility lane; discovery and hello responses advertise both profiles.
2026-06-17 12:45:30 +01:00
- Kotlin now has the same full interop RUDP proof shape as the other targeted
runtimes: the JVM CLI can serve schema-v0 hello/catalog/snapshot/mutation/fire
over `interop-rudp` , and it can dial a TypeScript full peer over the same
shared RUDP connection id and reliable ordered `schema` channel. TCP-framed
remains a compatibility lane for the interop peer; WebSocket remains the
JVM/Android-friendly client transport surface.
2026-06-16 13:36:34 +01:00
- TypeScript now also has a `CultNetSchemaCatalog` for remote schema
descriptors plus `CultNetPeer` request/fetch/sync helpers for
`cultnet.schema_catalog_request.v0` / `cultnet.schema_catalog_response.v0` .
`CultNetSchemaRegistry` remains the local definition owner; the catalog owns
imported descriptors so callers do not treat raw response objects as state.
2026-06-16 13:53:12 +01:00
- TypeScript now has the matching `CultNetShardCatalog` and peer
request/fetch/sync helpers for
`cultnet.shard_catalog_request.v0` / `cultnet.shard_catalog_response.v0` .
Shard descriptors can be filtered by schema id and record key without
2026-06-16 15:12:12 +01:00
requiring callers to inspect raw response maps. The built-in schema registry
also advertises the shard catalog request/response wire-message schemas, so
discovery matches the helper surface.
2026-06-16 00:38:48 +01:00
- Kotlin now mirrors the CultMesh stream catalog shape for Android-adjacent
media, sensor, tensor, and byte streams: stream declaration, clock metadata,
preferred body transports, consumer negotiation, copy-budget classification,
2026-06-16 10:02:07 +01:00
max in-flight frame pressure, latest-frame cursors, and watch callbacks for
stream declarations plus latest-frame publication.
2026-06-16 00:50:29 +01:00
- Kotlin now has a branded `CultMesh` facade matching the C#/TypeScript/Python
2026-06-16 10:43:54 +01:00
entrypoint pattern for local nodes, schema catalogs, shard catalogs, Verse
catalogs, peer catalogs, authority lease catalogs, stream catalogs, and RUDP
client/server construction. Kotlin also parses advertised
`rudp://host:port` endpoints and can build a RUDP client directly from a peer
2026-06-17 05:42:02 +01:00
card contact hint or the first peer authorized by the authority lease catalog.
The facade can now also return a connected RUDP client from a direct endpoint,
peer card, or authorized peer lookup, so schema-message transport helpers can
use RUDP without caller-side handshake ceremony. The facade delegates to the
same owners as the top-level helpers instead of creating a second authority
path.
2026-06-16 12:57:54 +01:00
- Kotlin WebSocket and RUDP transports now expose catalog fetch/sync helpers for
schema and shard catalogs. The helpers send standard schema-v0 requests,
require the matching response schema, and apply through the caller's catalog,
giving JVM/Android callers the same client ergonomics Python already had
2026-06-16 14:42:57 +01:00
without making the transport own catalog truth. Both adapters implement the
shared `CultNetSchemaMessageTransport` shape so the helper logic has one
owner across Kotlin stream and RUDP paths.
2026-06-16 16:03:18 +01:00
- Kotlin now also has a built-in schema catalog factory on the branded
`CultMesh` surface. It advertises the Kotlin-supported CultNet/CultMesh
request and response message descriptors, including schema catalog, shard
catalog, shard log, Verse catalog, peer exchange, and the shared transport
2026-06-16 16:22:18 +01:00
profile contract. The branded factory accepts the same schema-id, kind, and
inline-schema filters as the catalog request path, while still returning
ordinary `CultNetSchemaCatalog` state. Descriptors for contracts already
present in the canonical schema set use those schema ids and content hashes;
Kotlin-local descriptor bodies use schema-version ids until shared schema
files exist. Transports do not own catalog truth.
2026-06-16 10:02:07 +01:00
- Kotlin authority lease catalogs now also expose watch callbacks, so JVM and
Android clients can react to lease changes without treating peer-card contact
2026-06-16 16:45:21 +01:00
hints as trust. Kotlin peer catalogs also expose authorized-peer lookup
helpers, and the branded `CultMesh` facade can create a RUDP client from the
first peer authorized for a Verse role while still delegating the trust check
to the authority lease catalog.
2026-06-16 04:58:06 +01:00
- Rust now has a small `CultMesh` facade for its substrate role: peer cards,
2026-06-16 16:26:04 +01:00
sorted peer catalogs, authority lease catalogs, schema registry factories,
shard catalog factories, `rudp://host:port` endpoint parsing, and RUDP
2026-06-16 17:01:37 +01:00
client/server construction from endpoint, peer-card contact hints, or the
first peer authorized by the authority lease catalog for a Verse role. The
2026-06-16 16:26:04 +01:00
facade delegates to the existing Rust schema registry, shard catalog, and RUDP
socket transport owners; discovery contact remains separate from trust, which
2026-06-17 06:04:00 +01:00
is still gated by the authority lease catalog. The facade can now also return
a connected RUDP client from a direct endpoint, peer card, or authorized peer
lookup. Rust RUDP transports now also send and receive typed
`cultnet.schema.v0` messages on the reliable ordered `schema` channel, so
callers do not have to hand-encode MessagePack payloads or hand-roll the
client handshake before using the shared RUDP pipe.
2026-06-16 14:58:35 +01:00
- Rust now also has substrate-shaped shard catalog helpers:
`CultNetShardDescriptor` , `CultNetShardCatalog` , request filtering by schema
id and record key, response creation, response application, and built-in
schema registry entries for `cultnet.shard_catalog_request.v0` /
`cultnet.shard_catalog_response.v0` . This gives Rust the same topology
vocabulary without claiming stream catalog or production game-session server
ownership.
2026-06-16 19:02:25 +01:00
- The remaining adoption work beyond the current role-scoped parity claim is
to finish production service-body migration behind the shared transport
ports, then wire any remaining daemon/socket reconnect loops through the
shared controller. C# built-in LiteNetLib service wrappers now register
transport-aware `CultNetServerPeer` listeners instead of requiring each bridge
to bounce through `NetPeer` , TypeScript exposes a transport-first TCP peer
helper, C# schema-v0 service clients consume `ICultNetSchemaClient` , and the
core schema-message RUDP matrix is live in the TypeScript interop gate;
broader service adoption remains the unclaimed layer.
2026-06-14 22:06:09 +01:00
## RUDP Packet Contract V0
`cultnet.transport.rudp.v0` packets start with a fixed binary header, followed
by a UTF-8 channel id and payload bytes. All integer fields are unsigned
2026-06-14 22:20:49 +01:00
big-endian. The first deterministic fixture is live in TypeScript, C#, Rust,
2026-06-16 01:07:17 +01:00
Python, and Kotlin; every future runtime must port it byte-for-byte before
2026-06-14 22:20:49 +01:00
runtime-specific resend loops are allowed to claim parity.
2026-06-14 22:06:09 +01:00
| Offset | Size | Field | Notes |
| --- | ---: | --- | --- |
| 0 | 4 | magic | ASCII `CNR0` |
| 4 | 1 | version | `0` |
| 5 | 1 | packet type | `1=connect` , `2=accept` , `3=data` , `4=ack` , `5=ping` , `6=pong` , `7=disconnect` |
| 6 | 1 | flags | bit 0 reliable, bit 1 ordered, bit 2 sequenced, bit 3 fragmented |
| 7 | 1 | header bytes | fixed header plus channel id bytes |
| 8 | 4 | connection id | peer/session binding token |
| 12 | 4 | sequence | packet sequence number |
| 16 | 4 | ack | latest received sequence being acknowledged |
| 20 | 4 | ack mask | selective acknowledgement mask for prior packets |
| 24 | 2 | fragment id | `0` when not fragmented |
| 26 | 2 | fragment index | zero-based fragment index |
| 28 | 2 | fragment count | total fragments, `0` when not fragmented |
| 30 | 4 | payload bytes | payload length |
| 34 | 1 | channel id bytes | UTF-8 byte count, max 255 |
| 35 | 1 | reserved | `0` |
| 36 | n | channel id | UTF-8 channel id |
| 36+n | m | payload | transport-neutral payload bytes |
Canonical reliable ordered data fixture:
```text
packetType=data
connectionId=0x01020304
sequence=0x0000002a
ack=0x00000029
ackMask=0x80000001
channelId=schema
flags=reliable|ordered|fragmented
fragmentId=7
fragmentIndex=1
fragmentCount=3
payload=hello
hex=434e523000030b2a010203040000002a0000002980000001000700010003000000050600736368656d6168656c6c6f
```
2026-06-14 21:28:23 +01:00
2026-06-14 20:32:25 +01:00
## Reliable UDP Semantics To Lift From LiteNetLib
The portable RUDP contract must cover at least:
- connection handshake with application connection key support;
- peer id/session id binding;
- ping and timeout detection;
- reliable ordered channel delivery;
- unreliable channel delivery for realtime observations/input;
- sequenced delivery for latest-state streams;
- duplicate suppression;
- ack masks or equivalent selective acknowledgement;
- resend windows and retransmission timers;
- MTU-safe fragmentation and reassembly;
- disconnect reason propagation;
- bounded send queues and observable backpressure;
- deterministic wire fixtures for packet encode/decode in every runtime.
Until those are runtime-owned CultNet contracts, the runtimes do not truly
"speak the same language"; they are only translating documents after somebody
else already solved the pipe.