CultLib/packages/cultnet-rs

CultNet RS

cultnet-rs is the Rust sibling of @gamecult/cultnet-ts: typed MessagePack messages, 4-byte length-prefixed direct-pipe framing, CultLib-shaped security helpers, and CultCache replication without making callers paw through raw envelopes like we lost a bet.

The contract is intentionally boring:

• cultnet.schema.v0 sends schema-versioned MessagePack objects.
• gamecult.networking.v0 maps the legacy C# union shape explicitly.
• schema discovery uses explicit catalog request/response messages; no inbound auto-detect sludge.
• put and snapshot travel only as raw messages that carry the canonical MessagePack payload bytes; the receiver decodes them through registered types. Delete carries ids.
• hello messages advertise supportedMutationContracts, so callers discover which document types are read-only, which accept typed intents, which authority owns the mutation, and which receipt documents prove the outcome.
• payloads are decoded through registered Rust types before entering the cache.

This crate is not an HTTP wrapper. It is the wire vocabulary Epiphany, Ghostlight, VoidBot, and the rest of the swarm can share.

The public API surface is the schema plus its mutation contracts. A runtime does not expose a pile of bespoke verbs and hope everyone remembers the ritual; it advertises typed documents, typed intents, and typed receipts. Polite machines knock on the contract before touching the furniture.

Receipts

cargo test

The initial tests prove:

• CultLib-compatible AES-GCM string encryption and HMAC session tokens
• 4-byte big-endian MessagePack framing
• schema-versioned message round trips
• legacy gamecult.networking.v0 login mapping
• schema discovery catalog responses with canonical JSON schema hashes
• shard catalog request/response filtering and response application
• raw snapshot replication that preserves the original payload bytes
• raw snapshot replication into a local same-schema Rust alias type
• document mutation contract advertisement through hello frames and registries

Schema Discovery

cultnet-rs now ships a built-in schema registry for the shared swarm contract surface:

• core wire messages
• legacy gamecult.networking.v0 auth/sample payloads
• schema catalog request/response messages
• shard catalog request/response messages
• the canonical ghostlight.agent-state document payload schema

Use builtin_schema_registry() or CultMesh::create_builtin_schema_registry() when you want the standard catalog, or register your own closed-world schema set with CultNetSchemaRegistry / CultMesh::create_schema_registry(). Discovery stays explicit on purpose: peers advertise only the contracts they were compiled to understand, the same way CultCache only consumes the document types you registered instead of pretending polymorphism is a public park.

Shard Catalogs

Rust now exposes the same shard topology vocabulary as the other runtimes without claiming to be the full C# service body:

use cultnet_rs::{CultMesh, CultNetMessage, CultNetShardDescriptor};

let mut catalog = CultMesh::create_shard_catalog();
catalog.upsert(CultNetShardDescriptor {
    shard_id: "notes-a".to_string(),
    owner_runtime_id: "rust-primary".to_string(),
    epoch: 3,
    is_primary: Some(true),
    schema_ids: vec!["note.v0".to_string()],
    key_prefix: Some("note:".to_string()),
    primary_endpoints: vec!["rudp://127.0.0.1:4100".to_string()],
    replica_endpoints: vec![],
    read_replica_endpoints: vec![],
    region: None,
    authority_lease_id: None,
})?;

let response = catalog.create_catalog_response(&CultNetMessage::ShardCatalogRequest {
    message_id: "discover-shards".to_string(),
    schema_ids: Some(vec!["note.v0".to_string()]),
    record_keys: Some(vec!["note:1".to_string()]),
})?;

CultNetShardCatalog::apply_response(...) imports remote cultnet.shard_catalog_response.v0 descriptors into the local catalog. The catalog owns topology inspection only; shard-log serving, daemon policy, and game-session authority remain separate responsibilities.

Local Fast Lane

cultnet-rs now mirrors the raw replication seam from @gamecult/cultnet-ts:

• cultnet.document_put_raw.v0
• cultnet.snapshot_response_raw.v0

Those messages carry the exact persisted MessagePack payload bytes from CultCache along with the typed envelope metadata. Combined with CultCache::put_envelope::<T>(), that lets a bit-compatible neighbor ingest the document without re-encoding the payload first.

The receiving Rust type does not have to be the sender's concrete Rust type. If the local registry binds a different DatabaseEntry to the same schema id, sync_raw_document_from_snapshot_response::<LocalAlias>(...) hydrates one local alias type directly:

let mut target_registry = CultNetDocumentRegistry::new();
target_registry.register(CultNetDocumentBinding::for_entry_with_schema_id::<UiNote>(
    "aetheria.note.v1".to_string(),
    "aetheria.note.v1".to_string(),
));

let note = target_registry.sync_raw_document_from_snapshot_response::<UiNote>(
    &mut target_cache,
    &snapshot_response,
    "note:bridge",
)?;

That still is not zero-copy in the religious sense. Frames allocate, bytes move, and the receiving cache still decodes once to keep typed reads and validation honest. The win is narrower and realer: identical payload bytes stop getting decoded into generic sludge and then encoded right back into the same bytes for no reason.

Reactive Documents

For local state that should feel owned by the caller, Rust can wrap a registered CultCache record as a managed reactive document:

use std::sync::{Arc, Mutex};
use cultnet_rs::{CultNetReactiveDocumentOptions, CultNetDocumentRegistry};

let cache = Arc::new(Mutex::new(target_cache));
let note = registry.reactive_document::<UiNote>(
    Arc::clone(&cache),
    "note:bridge",
    CultNetReactiveDocumentOptions::default(),
)?;

{
    let current = note.current();
    current.lock().unwrap().body = "local prediction".to_string();
}

The handle polls the serialized current value on the configured debounce cadence and flushes changed state back through the typed cache. update(...), set_current(...), mark_dirty(), and flush() are available when the caller wants a more explicit Rust shape.

When a canonical document put arrives while local state is dirty, apply_raw_document_put_message(...) records a CultNetReactiveDocumentReconciliation: the canonical value, the predicted local value, and a delta that can be smoothed by the caller. CultCache payloads serialize by numeric field slot, so Rust tuple-backed deltas use slot keys such as "0" and "1" when field names are not present on the wire.

CultMesh Rust Facade

Rust is still the low-level substrate runtime, not a clone of the C# game server. It does now expose the small CultMesh entrypoint needed for practical contact and authority ergonomics:

use cultnet_rs::{
    CultMesh, CultMeshAuthorityLease, CultMeshPeerCard, CultMeshRudpClientOptions,
    CultMeshRudpSocketOptions, CultNetMessage, CultNetSchemaKind,
};
use chrono::{Duration, Utc};

let schemas = CultMesh::create_builtin_schema_registry()?;
let shared_contracts = schemas.list(&cultnet_rs::CultNetSchemaCatalogOptions {
    include_schema_json: false,
    schema_ids: None,
    kinds: Some(vec![CultNetSchemaKind::SharedContract]),
});

let mut server = CultMesh::create_rudp_server(
    "rust-server",
    0x1020_3040,
    CultMeshRudpSocketOptions::default(),
)?;
let port = server.profile.transports[0].port.unwrap();

let peer = CultMeshPeerCard::new(
    "rust-server",
    "local",
    [format!("rudp://127.0.0.1:{port}")],
)
.with_roles(["schema"])
.with_authority_lease_id("lease:rust-server");

let now = Utc::now();
let mut peers = CultMesh::create_peer_catalog();
let mut leases = CultMesh::create_authority_lease_catalog();
peers.upsert(peer.clone())?;
leases.upsert(CultMeshAuthorityLease {
    lease_id: "lease:rust-server".to_string(),
    verse_id: "local".to_string(),
    peer_id: "rust-server".to_string(),
    roles: vec!["schema".to_string()],
    shard_ids: Vec::new(),
    issuer_runtime_id: None,
    valid_from: now - Duration::minutes(1),
    expires_at: now + Duration::minutes(1),
})?;

let mut client = CultMesh::connect_rudp_client_for_authorized_peer(
    "rust-client",
    0x1020_3040,
    &peers,
    &leases,
    "local",
    "schema",
    None,
    now,
    CultMeshRudpClientOptions {
        socket_options: CultMeshRudpSocketOptions::default(),
        connect_payload: b"join".to_vec(),
        ..CultMeshRudpClientOptions::default()
    },
)?;
client.send_schema_message(&CultNetMessage::SchemaCatalogRequest {
    message_id: "rust-schema-catalog".to_string(),
    include_schema_json: Some(false),
    schema_ids: None,
    kinds: Some(vec![CultNetSchemaKind::DocumentPayload]),
})?;

create_rudp_client... remains available when the caller intentionally owns the handshake and polling loop. connect_rudp_client... performs the client handshake before returning the same schema-message-capable RUDP transport.

For caller-owned reconnect loops, CultNetRudpReconnectLoop keeps transport construction outside the library while sharing the portable retry controller:

use cultnet_rs::{
    CultNetReconnectPolicyOptions, CultNetRudpReconnectLoop, create_reconnect_policy,
};

let policy = create_reconnect_policy(CultNetReconnectPolicyOptions::default());
let mut reconnect = CultNetRudpReconnectLoop::new(policy, b"join".to_vec(), || {
    CultMesh::create_rudp_client_for_peer(
        "rust-client",
        0x1020_3040,
        &peer,
        CultMeshRudpSocketOptions::default(),
    )
});

reconnect.start()?;
let decision = reconnect.handle_closed(now_ms, 0);
if decision.is_some() {
    reconnect.reconnect_if_due(now_ms)?;
}

CultMesh::parse_rudp_endpoint(...) handles advertised rudp://host:port contact hints, and CultMeshAuthorityLeaseCatalog keeps trust separate from discovery. A peer card can say where to dial; peers.first_authorized(...) and CultMesh::create_rudp_client_for_authorized_peer(...) only use that contact hint after a lease says the peer may own the requested role or shard.