Modularize CultMesh transport planes

This commit is contained in:
Meta Vens 2026-07-19 17:57:26 +01:00
commit c16163a82f
19 changed files with 2162 additions and 171 deletions

View file

@ -2,6 +2,8 @@
Incident record: [CultMesh bulk content over custom RUDP, July 2026](postmortem-2026-07-cultmesh-bulk-rudp.md).
Physical-plane authority: [CultMesh transport planes](transport-planes.md).
## Objective
CultMesh should give an application one typed, watchable route to a Verse,
@ -676,16 +678,17 @@ body in process.
**Owner:** CultMesh negotiation selects a body transport from provider-owned
capabilities and consumer demand. The selected transport owns byte movement;
`CultMeshContentTransferService` continues to own content identity, resumable
verification, and atomic cache promotion. CultNet RUDP does not own bulk-body
performance.
verification, and atomic cache promotion. TCP owns remote immutable content;
CultNet RUDP does not own bulk-body performance.
**Inputs:** content hash and size, provider-advertised transport candidates,
consumer-supported transports, same-machine evidence, and platform support.
**Outputs:** an authorized mapped body for same-machine deployments, or a
dedicated remote byte stream feeding the existing verification/promotion owner.
Typed control state, reactive variables, commands, and receipts remain CultNet
messages and are not smuggled into the bulk stream.
dedicated TCP byte stream feeding the existing verification/promotion owner.
Schemas, commands, receipts, and manifests use framed TCP CultNet messages.
Realtime state uses a separately negotiated QUIC stream or datagram and is not
smuggled through either snapshots or the immutable-content stream.
**Derived state:** selected plane, physical endpoint, mapped-file descriptor,
stream progress, and transport telemetry. None can change content identity,

View file

@ -0,0 +1,74 @@
# CultMesh Transport Planes
CultMesh selects a transport per workload. It does not ask one wire protocol to
be equally good at files, realtime state, and same-machine memory access.
## Authority map
**Owner:** `CultMeshSessionManager` selects an advertised route through a
registered connector for each traffic class. A connector owns only its physical
connection and byte movement.
**Inputs:** stable endpoint identity, advertised physical candidates, connector
support and priority, caller cancellation, and locality evidence for body
negotiation.
**Outputs:**
| Workload | Preferred plane | Contract |
| --- | --- | --- |
| Schemas, commands, receipts, manifests | TCP | `cultnet+tcp://` through `ICultMeshTransportConnector` |
| Immutable chunks and other file-shaped bodies | TCP byte stream | `cultmesh-content+tcp://` through `ICultMeshContentTransportConnector` |
| Realtime state | QUIC streams or datagrams | `ICultMeshRealtimeTransportConnector` with an explicit delivery mode |
| Same-machine SoA and large bodies | mapped/shared memory | body transport negotiation |
The TCP content plane sends typed CultNet request and response headers, then
streams raw chunk bytes outside the schema envelope. The transfer service owns
range hashing, resume checkpoints, provider failover, full-body verification,
and atomic promotion regardless of the selected content connector.
`CultMeshClient` installs the TCP schema and TCP content connectors by default.
Passing explicit connector lists replaces those defaults.
Realtime frames declare whether they require reliable ordered delivery,
latest-only delivery, or unreliable delivery. The contract is ready for a QUIC
connector; no RUDP implementation is installed implicitly in its place.
**Derived state:** connector choice, physical endpoint, connection health, and
transport diagnostics. None of these grant provider authority or become content
identity.
**Forbidden writers:** applications and renderers do not choose unadvertised
endpoints, implement reconnect loops, or bypass verification. Schema messages
must not carry bulk bodies. RUDP/LiteNetLib cannot become an implicit default
for any traffic class. QUIC does not own schemas or immutable files merely
because it can transport bytes.
**Shared paths:** discovery and identity resolution remain common. Each traffic
class has its own connector set, connection cache, priority tiers, and failure
state. All content connectors feed the same transfer and promotion owner.
**Cut line:** the former RUDP content server is
`CultMeshLegacyRudpContentServer`, and its connector must be registered
explicitly. It has basement priority and exists for compatibility and parity
measurement. The legacy datagram schema connector is likewise explicit and
lower priority than TCP. Existing hot-state publishers that still package
payloads as schema messages must move to the realtime connector contract; the
new seam does not pretend that migration has already occurred.
## Security and release gate
The current TCP connectors are a local-development transport and are plaintext.
Remote release requires authenticated encryption and binding the authenticated
peer to the advertised provider identity. Adding TLS must not move discovery,
authorization, content verification, or application semantics into the TCP
adapter.
## Local parity evidence
On 2026-07-19, the parity harness moved a 13 MiB payload on loopback using
1 MiB content chunks. Raw TCP reached 127.4 MiB/s, verified CultMesh TCP content
reached 59.0 MiB/s, raw MsQuic reached 51.5 MiB/s, and legacy CultMesh RUDP
reached 10.7 MiB/s while emitting 18,112,867 wire bytes. CultMesh TCP includes
chunk hashing, durable checkpoints, final hashing, and atomic promotion, so this
is not a claim of raw protocol parity. It is a repeatable workload comparison
and leaves the remaining framework overhead visible.