DistrictServerCSharp: .NET 8 port of the C++ district server (draft, refs #12)

[eaxiumnet]

Implements the C# port proposed in #12. Opened as a draft: the history is reviewable and every offline gate is green, but the one verification gap named in #12 — a live-client smoke test — is still open, and no maintainer feedback on the architecture has landed yet. Nothing here removes, rewrites, or competes with the C++ tree.

What this adds

DistrictServerCSharp/ — a .NET 8 reimplementation of DistrictServer.cpp (~14k lines) split by responsibility, plus two drift gates under Tools/. 42 files, +14,220 lines, zero lines deleted. DistrictServer/ (C++) is untouched and remains the protocol oracle and the rollback path.

Layer	Contents
Bits/, Crypto/, Protocol/, Net/	UE3 bit primitives, XTEA/BTEA, packet parse/build, field decoders, UDP listener
Handshake/	AUTH → USES → WELCOME → JOIN → district-enter answer, channel sequencing, binary NMT control
Core/	reliable TX queue + ACK retirement/retry, transport state, packet diagnostics, lifecycle resets
Gri/, Streaming/, SpawnZone/	GRI match-start, level-streaming plan, spawn-zone markers + selection
Pawn/, Controller/	ACK-gated pawn bootstrap + possession, remote-pawn multiplayer + dead-peer lifecycle, controller field decode
Packages/	cooked-package net-index resolver (parses cooked .u directly)
WorldControl/	world registration + character handoffs
Drive/	in-process two-player end-to-end harness

Commits

Seven incremental commits, each building on the last, bottom-up so review can follow the wire layer before the services that use it:

06dcebc	scaffold: project skeleton
4c9bd0b	wire layer: bit primitives, XTEA/BTEA, packet parse/build, field decoders
52130de	core services: handshake, reliable queue, channel sequences, transport state, diagnostics
67e69d9	subsystems: GRI match-start, streaming, spawn zones, pawn lifecycle, remote pawn, controller, resolver
c48183b	drive harness: in-process two-player verification
a28cd8d	docs/tools: PORTING.md function map + drift-gate and deploy-sync checkers
3c9fd1f	net: the district UDP listener (completes the port)

Verification

Run against a pristine git archive export of the branch tip into an empty directory, so nothing untracked can contribute:

dotnet build -c Release     0 Warning(s)  0 Error(s)
--selftest                  SELF-TEST PASS
--drive                     DRIVE PASS

--drive milestones: registered at World Server → WELCOME → both account sequences complete → remote pawn opened in both directions → ClientNotifyTransferComplete.

--resolver-check PASS, run in a tree with a real cooked APBGame.u configured (it needs a local client path, so it is not part of the pristine-export run): parses the package and reproduces the live C++ net indices exactly — controller ordinal 12426, holdable 15985 → 47088, storage 25478 → 56581.

Port completeness is machine-checked rather than asserted. Tools/check_port_sync.py inventories every C++ function and fails if one has no C# home: DistrictServer.cpp 175/175 mapped, 0 not-ported, 0 unmapped. PORTING.md §7 lists the only intentional exclusions — dead Unreal.cpp (not in the C++ build, zero callers) and three zero-caller raw-float helpers whose behaviour is covered inline by BitConverter.SingleToUInt32Bits. Note that --all also reports ~68 doc gaps for the ApbUdp.cpp bit/parse primitives; those are ported wholesale as the Bits//Protocol/ layers and mapped at layer granularity, so the gate exits 0 for them by design. Only a non-zero port gap count means something is genuinely unported.

What is NOT proven

No live-client session has been run against this build. The C# port is what is currently deployed in my local stack (Social 6969 / Financial 6970 / Waterfront 6971, managed apphost, all three up since 13:31:41 today), but every district log it has produced so far is from --drive — the only AUTH identities present are the harness accounts 0000000001 and 0000000002, never a real client account. So the offline gates and the simulated two-player path are green; end-to-end behaviour against the real 1.1 client is untested on this branch. That test is what should move this out of draft, and I would rather state the gap than let green CI-style output imply coverage it does not have.

Relationship to the open C++ PRs

Three behavioural fixes were found while porting and apply to both trees. #13 lands them in the C++ oracle; they are native to the C# code here, so the two implementations stay wire-identical rather than diverging:

• Per-endpoint channel sequences instead of a global counter.
• Possession gate keyed by client endpoint (address, port) instead of account id. The C++ used a global account-id set that was never cleared, so a reconnect of the same account from a new socket had its district-enter ASK received but never answered — insert returned false — and the client parked at "Entering district" forever.
• Registration reply framing on the world-control link.

#14 is the WorldServer half of the registration-lifecycle work and is independent of this branch.

Review notes

Happy to split this into smaller PRs, restructure the layering, or change anything about the approach — including keeping it on the fork indefinitely if a parallel implementation is not wanted in-tree. The commit boundaries are designed so any prefix of them is a coherent, buildable subset if you would prefer to take it in stages.

Refs #12.

🤖 Generated with Claude Code

[eaxiumnet]

Pushed 75f7d5c: four C++/C# fidelity divergences, all silent behaviour
differences rather than compile errors. Each was checked against
DistrictServer.cpp directly.

#	Divergence	Oracle anchor	Effect before the fix
1	ProtectOutgoingPacket aliased the caller's buffer instead of copying it	:1412 (packet passed by value)	DistrictCrypto.Encrypt is in place, so the caller's plaintext became ciphertext. ReliableQueue stored that array as ClearPacket and re-encrypted it on retry — deterministic for spawn-zone / HUD-marker labels, which this build never ACKs. First send was always correct, every resend was garbage.
2	JOIN never cleared per-account controller feedback state	:13137-13142	A reconnect reusing the same account id kept the previous startup/marker barrier, so field 372 sent no fresh marker and the player was never possessed. Lifecycle.ResetControllerFeedback was already wired but had no call site.
3	OnMarkersSent used a raw Dictionary indexer	n/a (C++→C# semantics)	Unlike std::map::operator[], the .NET indexer getter throws KeyNotFoundException — straight out of the UDP receive loop. Fix 2 makes that window reachable, so the two had to ship together.
4	Spawn-location latch gated on IsActionDistrict, by-channel reference form only	:12474-12506, helper at :397	The oracle gates the latch on firstReceipt alone and accepts two reference forms: the bridge channel (action) and the static spawn-zone template NetIndex 72913/72914 (Social). On Social the latch never ran at all, so PawnLifecycleService / RemotePawnReplication found no selected location and the pawn ignored the chosen zone.

Divergence 4 is worth calling out separately: it was not in the audit. It
surfaced only after Tools/check_port_sync.py was repointed at the real port.
The gate had ProtectOutgoingPacket mapped to a dead
DistrictCrypto.ProtectOutgoingPacket duplicate (zero callers, and it diverged
from the oracle twice on its own — rejecting < 8 bytes the oracle zero-pads,
and a slice that threw on unaligned input). That dead copy is gone and the
mapping now names HandshakeService. With the gate honest it reported
TryGetSpawnZoneLocation as a genuine port gap, which is divergence 4.

Gate now: 160/160 mapped, 0 doc gaps, 0 port gaps. Build clean, 0 warnings.

Not yet exercised against a live client — these are source-fidelity fixes
verified against the oracle and the drift gate, not observed client behaviour.
The two that most want a live check are 2 (rejoin without restarting the
district) and 4 (select a Social spawn zone and confirm the pawn lands on it
rather than a fallback).

[eaxiumnet]

Provenance audit: three doc claims asserting a C++ counterpart that does not exist

Follow-up to the fidelity pass above (048552e). While checking one comment I could not reproduce, I found three claims in this branch's own docs that point at C++ code which isn't there. All three are docs/comments — no code path changed, build clean.

#	Claim	Reality
1	BitWriter.WriteCompressedRotator: "Verified round-trip against the C++ (yaw 16384 reconstructs to 16384)"	grep -r Rotator DistrictServer/ → nothing. The oracle has WriteCompressedVector (ApbUdp.cpp:262) and one AimRotation int READ (:2410). Neither side has a rotator reader, so there is no round-trip harness anywhere.
2	PORTING.md §3.8 C++ column: BuildUnreliableActorVectorFieldPacket, BuildUnreliableActorRotatorFieldPacket	Both phantoms. The oracle has exactly one: BuildUnreliableActorFloatFieldPacket (ApbUdp.cpp:1221 → DistrictServer.cpp:10753) — which had no row at all.
3	PORTING.md §7.2: BuildActorRotatorFieldPacket "(zero C++ callers)" + "the raw-float paths are unused by the port"	Phantom again; and FloatToWireBits (:1828) / WriteFloatBits (:2185) have live callers — PRI stats :1867/:1873, non-compressed HUD-marker location :2264-:2266. Both are mirrored, inline via BitConverter.SingleToUInt32Bits (PacketBuilders.cs:405, :583-:585, :918-:920, :1180-:1182).

Fixes: #1 relabelled PORT-ORIGINAL — encoding is client-RE-derived and hand-checked only, explicitly not yet exercised against a live client (the encoding description itself is untouched, it's the verification claim that was wrong). #2 the real builder is now mapped, with the vector/rotator ones marked as port additions for the remote-pawn path. #3 reworded to state the live callers and that they stay in §7 only because there's no named C# home for a §3 row.

Side effect worth noting: deleting the §7 phantom makes the gate's arithmetic add up — it had been listing 8 not-ported entries while only ever matching 7.

default  MAPPED 160, NOT-PORTED 0, UNMAPPED  0  (0 doc,  0 port gaps)
--all    MAPPED 161, NOT-PORTED 7, UNMAPPED 61  (61 doc, 0 port gaps)

MAPPED 160 → 161 and doc gaps 62 → 61 are the newly-documented float builder. The stale ~68 in §7 is now the measured 61.

Net effect of this and the previous commit: the port's own docs no longer claim verification that was never performed. The one place a live-client check would now buy the most is WriteCompressedRotator — it is the only wire encoding in the tree with no C++ counterpart and no reader to check itself against.