diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index 3672d9c7..06bdb5e2 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -1,13 +1,16 @@ # CultNet Transport Parity Map CultNet payload parity is not enough. The runtimes can already trade schema-v0 -MessagePack documents through the interop lane, but realtime networking still -has one real owner: the C# `GameCult.Networking` stack on LiteNetLib. The other -runtimes mostly speak a TCP-framed dialect for tests and local services. +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. 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 -network language. +network language. Runtime role boundaries live in +[runtime-parity-scope.md](runtime-parity-scope.md). ## Objective @@ -123,8 +126,8 @@ lets the runtimes stop guessing what kind of pipe a peer is offering. ## Implementation Sequence -1. Add `cultnet.transport_profile.v0` as a shared contract in C#, TS, Rust, and - Python catalogs. +1. Add `cultnet.transport_profile.v0` as a shared contract in C#, TS, Rust, + Python, and Kotlin catalogs. 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 @@ -133,12 +136,12 @@ lets the runtimes stop guessing what kind of pipe a peer is offering. `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 - with C#/TS/Rust/Python ping, loss, reordering, fragmentation, reconnect, and - schema-message tests. + with C#/TS/Rust/Python/Kotlin ping, loss, reordering, fragmentation, + reconnect, and schema-message tests. Current progress: -- Steps 1-3 are live in C#, TypeScript, Rust, and Python. +- Steps 1-3 are live in C#, TypeScript, Rust, Python, and Kotlin. - 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 @@ -156,13 +159,13 @@ Current progress: `TcpFramedTransportConnection` with schema-channel `send`, `receive`, and transfer stats. The Rust interop peer advertises and uses that shared port instead of owning raw TCP frame I/O directly. -- TypeScript, C#, Rust, and Python now share the first +- TypeScript, C#, Rust, Python, and Kotlin now share the first `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. -- TypeScript, C#, Rust, and Python now share the first deterministic RUDP +- TypeScript, C#, Rust, Python, and Kotlin now share the first deterministic RUDP 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 @@ -239,7 +242,7 @@ Current progress: `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 big-endian. The first deterministic fixture is live in TypeScript, C#, Rust, -and Python; every future runtime must port it byte-for-byte before +Python, and Kotlin; every future runtime must port it byte-for-byte before runtime-specific resend loops are allowed to claim parity. | Offset | Size | Field | Notes | diff --git a/docs/runtime-parity-scope.md b/docs/runtime-parity-scope.md new file mode 100644 index 00000000..b3367cfa --- /dev/null +++ b/docs/runtime-parity-scope.md @@ -0,0 +1,67 @@ +# Runtime Parity Scope + +This is the claim CultLib can make without turning evidence into incense. +Parity means the targeted runtimes speak the same wire language and expose +similar developer-facing entrypoints for the roles they own. It does not mean +every runtime clones the C# production server, LiteNetLib history, or hot-loop +memory layout. + +## Objective + +Cross-runtime parity has three layers: + +- Wire parity: shared CultCache file/state contracts, schema-v0 MessagePack + documents, transport profiles, and RUDP packets must cross runtime boundaries + without translation folklore. +- Feature parity: each runtime must expose the CultCache/CultNet/CultMesh + surfaces needed for its intended role, with unsupported production-server + ownership called out plainly. +- Ergonomic parity: callers should find a branded `CultMesh` entrypoint, + typed catalogs, discovery helpers, authority checks, stream surfaces, and + transport helpers instead of assembling raw maps and channel strings. + +SoA performance parity is deliberately not a cross-runtime requirement. C# +owns the CPU-local SoA table and shared-memory streaming body path. Other +runtimes may add native hot paths when their runtime role earns them, but they +do not need to mimic Unity/C# memory layout to speak CultNet or participate in +CultMesh. + +## Current Targeted Runtimes + +| Runtime | Role | Claimed parity | Not claimed | +| --- | --- | --- | --- | +| C# | Reference implementation and production game/server substrate | CultCache typed documents and SoA, CultNet schema-v0, LiteNetLib production path, shared transport profiles, shared RUDP socket transport, CultMesh node/session/catalog/stream/simulation surfaces | No need to abandon LiteNetLib before the CultNet adapter fully owns production service adoption | +| Python | Package runtime, local daemon endpoint, raw interop peer, typed state participant | CultCache/CultNet/CultMesh package surface, schema catalogs, shard catalogs/logs, local TCP CultMesh server, session/prediction/simulation fact helpers, authority leases, streams, RUDP codec/session/socket transport, benchmark evidence against C# cache paths | Universal C# throughput, full C# daemon/server stack, and RUDP as the only public service pipe | +| TypeScript | Node/browser-adjacent projection and interop runtime | CultCache parity tests, CultNet schema-v0 peer, transport profiles, TCP-framed transport port, shared RUDP socket transport, local CultMesh node/catalog/authority/stream ergonomics | Full C# game session/server stack | +| Rust | Low-level cache/transport/runtime substrate | CultCache/CultNet interop lane, transport profiles, TCP-framed port, shared RUDP codec/session/socket transport | Full CultMesh ergonomic facade or production game-session server | +| Kotlin | JVM/Android client substrate | Typed MessagePack cache, schema/shard catalogs, authority leases, stream catalog, branded `CultMesh` facade, RUDP client/server sugar, schema-v0 MessagePack over RUDP evidence | C# SoA store, full C# server daemon, or Unity hot-loop memory layout | + +## Evidence Gates + +- `packages/cultnet-ts/test/interop/cultnet-interop.test.ts` is the main live + wire harness. It covers schema-v0 interop and RUDP exchange across C#, + TypeScript, Rust, Python, and Kotlin, including loss, reordering, + fragmentation, disconnect reason propagation, ping/pong, and schema-v0 + MessagePack over RUDP for the runtimes currently wired into that message + lane. +- `packages/cultcache-py/PARITY.md` is the Python-specific audit ledger. Its + "Still Not Claimed" section is part of the contract, not an apology. +- `docs/cultnet-transport-parity.md` is the transport ownership map. It tracks + the remaining work to lower older TCP/LiteNetLib/WebSocket bodies behind the + shared transport port and expand RUDP adoption beyond the core proof. +- `packages/cultmesh-kotlin/README.md` records Kotlin's runtime role and + ergonomic surface, including the explicit non-claim around C# SoA storage. + +## Remaining Work Before A Full Completion Claim + +- Broaden service adoption so local servers and daemon paths use the shared + transport port consistently instead of keeping raw TCP/LiteNetLib/WebSocket + ownership in individual bodies. +- Extend RUDP interop evidence through reconnect policy and the wider + schema-message matrix, not only the current schema-frame and selected + schema-v0 message paths. +- Keep Kotlin ergonomic parity moving with Android/JVM-shaped APIs instead of + backfilling C# server responsibilities it should not own. +- Keep performance claims evidence-bound: C# owns SoA; Python has benchmark + comparison gates; other runtimes should advertise measured native hot paths + only when those paths exist.