GameCult/CultLib
Watch
9
0
Fork
You've already forked CultLib
 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
CultLib/docs/runtime-parity-scope.md
Meta Vens 5dbc0c29f5 Bound the RUDP receive path and refuse hostile sequences 
Clears the cultnet half of the retained debt. The two unported commits from the
retiring GameCult/cultnet-rs lineage were not portable as patches: this lineage
had reworked the same receive path with sequence domains and ACK horizons, and
applying them raised nine conflicts that would have reverted that work. Most of
what they added already existed here by another route -- received-sequence
history, fragment-set count and reassembly bytes are all bounded already. So
the gaps were taken rather than the patches.

Three were real. The per-channel maps grew without limit, and a peer picks its
own channel ids, so ordered and sequenced channel tracking is now capped at 64
each. The out-of-order hold buffer grew without limit, and a peer picks its own
send order, so it is capped at 1024 frames and 4 MB; sizes are computed from the
buffer rather than tracked in counters, which cannot drift.

The fourth was the sharpest. remember_received ran before the duplicate
early-return, so a single forged packet far past the current highest advanced
the receive state beyond every sequence still in flight and starved the
session. Such a packet is now refused without being remembered.

Reliable sequence exhaustion aborted the process through expect(). The capacity
gate that already guards the send window now also refuses when the sequence
space cannot cover the request, and allocation saturates rather than panicking
so no future path can reintroduce the abort.

Five tests cover the bounds and both refusals. cultnet-rs passes 103,
cultcache-rs 48, cultmesh-rs 7, and the TypeScript-Rust RUDP interop lanes pass
5 of 5 with the hardened peer, so legitimate traffic is unchanged.

The parity ledger now records what this actually leaves owed: these are
refusals, not wire-format changes, so the interop lanes stay green whether or
not the other four runtimes match. The gap will not announce itself.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-04 00:57:07 +02:00

9.2 KiB
Raw Blame History

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 with adapter profile, shared transport profiles, shared RUDP socket transport, C# multi-peer RUDP listener and schema service host, C# interop RUDP serve/dial path, connected RUDP CultMesh client helpers, RUDP-backed schema-client selection for rudp:// service endpoints, RUDP reconnect policy/controller and reconnect-loop helper, LiteNetLib client reconnect-controller adoption, schema-client transport port for service request/response clients, CultMesh node/session/catalog/stream/simulation/RUDP surfaces, authorized peer lookup 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, branded CultMesh node/schema/shard/Verse/peer/authority/stream/RUDP ergonomics, authorized peer lookup, shard catalogs/logs, schema-transport factory for raw client request/subscription flows, local TCP and RUDP CultMesh server listeners, Python interop RUDP serve/dial path, session/prediction/simulation fact helpers, RUDP codec/session/socket transport, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, 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, advertised schema/shard catalog wire contracts plus request/sync helpers, transport profiles, TCP-framed transport port and peer helper, shared RUDP socket transport, RUDP interop serve/dial path, RUDP reconnect policy/controller, RUDP reconnect-loop helper, branded CultMesh node/schema/shard/Verse/peer/authority/stream/RUDP ergonomics, authorized peer lookup Full C# game session/server stack
Rust Low-level cache/transport/runtime substrate CultCache/CultNet interop lane, schema and shard catalog helpers, typed same-schema alias hydration from raw snapshots, transport profiles, TCP-framed port, shared RUDP codec/session/socket transport, Rust interop RUDP serve/dial path, connected RUDP CultMesh client helpers, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, small CultMesh facade for schema registry, shard catalog, peer cards, authority leases, authorized peer lookup, RUDP endpoint parsing, and peer-card/authorized-peer RUDP client construction Full CultMesh game-session/server facade or production game-session server. packages/cultmesh-rs now holds a Rust stream and session surface -- node, document sets, RUDP document publication, stream descriptors, negotiation, stream catalog, and shared-memory frame rings -- but no interop lane exercises it, so it carries no cross-runtime parity claim
Kotlin JVM/Android client substrate Typed MessagePack cache, one-call typed snapshot document sync through local same-schema aliases, built-in schema catalog advertisement, schema/shard catalogs with shared schema-message transport fetch/sync helpers, authority leases, authorized peer lookup, stream catalog, branded CultMesh facade, WebSocket transport profile/connection helper, RUDP client/server sugar, connected RUDP CultMesh client helpers, Kotlin interop RUDP serve/dial path, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence C# SoA store, full C# server daemon, or Unity hot-loop memory layout

Evidence Gates

  • .github/workflows/cultnet-interop.yml is the hosted CI witness for the cross-runtime wire claim. It builds the TypeScript workspace, Kotlin interop peer, Rust/C# interop peers through the TypeScript harness, installs the Python package dependencies, then runs named RUDP lanes for Python, Rust, C#, and Kotlin, the RUDP impairment matrix, and the schema-v0 discovery lane.
  • 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 C#, Rust, Python, and Kotlin peers against TypeScript. Those RUDP schema-message tests also assert the advertised reconnectPolicy profile field from C#, Rust, Python, and Kotlin peers. Runtime-local tests cover the deterministic delay helper and reconnect controller in C#, TypeScript, Rust, Python, and Kotlin.
  • 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 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.

Expansion Work Outside The Current Parity Claim

The current claim is role-scoped feature, wire, and ergonomic parity across the targeted runtimes. The stronger claim that every production daemon/service body has already moved to native RUDP, or that every runtime clones the C# production server body, is deliberately not made.

  • Broaden production service adoption so remaining daemon paths use the shared transport port consistently. The C# built-in LiteNetLib service wrappers now register transport-aware CultNetServerPeer listeners instead of requiring NetPeer callbacks, and TypeScript TCP peer creation has a transport-first helper. C# Verse discovery, peer exchange, shard-log fetch, shard-snapshot fetch, and shard write forwarding clients now consume a schema-client transport port and select the C# RUDP schema client for rudp:// endpoints while keeping LiteNetLib for cultnet:// endpoints. Broader daemon adoption remains the unclaimed layer.
  • Extend RUDP adoption through daemon/socket reconnect loops. RUDP profiles now advertise the portable reconnect policy, runtime-local tests prove the shared controller across the targeted runtimes, and the C# LiteNetLib client plus C#/TypeScript/Rust/Python/Kotlin RUDP reconnect loops use that controller; broader service adoption remains a separate claim.
  • Keep Kotlin ergonomic parity moving with Android/JVM-shaped APIs instead of backfilling C# server responsibilities it should not own. Kotlin WebSocket and RUDP adapters now share one CultNetSchemaMessageTransport helper shape for schema/shard catalog request and sync flows.
  • Bring packages/cultmesh-rs under the wire claim. It arrived from a consumer repo where it grew outside any conformance harness, and its stream, negotiation, and shared-memory frame-ring surfaces have never been checked against the browser, Kotlin, and TypeScript CultMesh bodies they must interoperate with. Runtime-local tests pass; that is not a parity claim.
  • Carry the RUDP receive-path bounds to the other runtimes. Rust now caps tracked ordered and sequenced channels, caps the out-of-order hold buffer by frames and bytes, refuses a packet far ahead of the highest received so a forged sequence cannot starve a session, and reports reliable sequence exhaustion instead of aborting. C#, TypeScript, Python and Kotlin still accept all of it. These are refusals rather than wire-format changes, so the interop lanes stay green either way -- which is exactly why the gap will not announce itself.
  • 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.