Two defects the Carbon rig found, neither visible on a development loopback.
**The wipe id was null for every real session.** `Init` runs before the save is
loaded, so `SaveRestore.SaveCreatedTime` is not yet meaningful there and the id
resolved at load time stayed null for the life of the process — every frame
shipped without the field R12 splits history on. It was invisible because a
hot-reloaded plugin reads an already-loaded world and gets the right answer every
time; it took a server that BOOTED with the plugin installed, which is every real
one, to show `wipeId=none` beside a save sitting on disk. Resolved again at
`OnServerInitialized`, and lazily while still unknown.
**Unload blocked the main thread for two seconds against an unreachable sidecar.**
Observed as `hook 'Unload' took longer than 100ms [2002ms]` next to `link thread
did not stop cleanly` — phase 1's stall arriving by a different road. The link
thread sits in a blocking `TcpClient.Connect`, which has no timeout of its own
and cannot be woken; a host that REFUSES answers instantly, which is every
loopback test, and a host that DROPS does not answer at all. The connect is now
bounded, and waits on a stop handle of its own so a reload abandons it at once.
It cannot share `Wake`, which also means 'the queue has something in it' and is
signalled by every hook.
After: the same reload logs no slow-hook warning and no stranded thread.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
Fifteen hooks: presence, deaths, chat, gathering, raided structures, bans,
reports, login attempts and the wipe. Every frame now carries an envelope —
`type`, `serverId` and `wipeId` — built in one place so nothing can emit a frame
without one.
Three rules the code enforces structurally rather than by intention:
• A read-path hook never vetoes. Four of these are documented as "returning a
non-null value overrides default behavior", so every hook is declared `void`
and cannot answer. `CanUserLogin` is in the wave for what it observes.
• A hook that can fire more than once a second per player is a counter.
`OnDispenserGather` fires on every swing at a tree; it accumulates into a
per-player tally flushed once a minute as one `player.tally` frame, as a
delta rather than a running total.
• `wipeId` is derived here, from the save's creation time, because this is the
only component that can read it. PROTOCOL.md §8.2 reverses protocol 1 on
that point deliberately.
`server.hello` becomes a board rather than a greeting, and `players.online`
joins it; both are re-sent on connect and every 60 seconds, which is what makes
a restarted sidecar repopulate itself without asking.
`rg.hooks` reports which hooks have actually fired. Hooks bind by name and arity
through reflection on both frameworks, so a rename by Facepunch and a name
Carbon's catalogue omits present identically — as silence. This is the standing
answer to both, and it outranks either catalogue because it is a measurement.
The repository had no `.gitea/workflows/` at all. `scripts/checkPlugin.js` asks
the three questions a compiler here cannot: every hook is in `ExpectedHooks`, so
`rg.hooks` can see it; every hook is `void`, unless answering is a decision
written down in `ANSWERS_DELIBERATELY`; and `ProtocolVersion` agrees with
`overlay.toml`, which is what stops a bundle that will not compose. The void
rule is inverted on purpose — a list of *vetoable* hooks would have to be
maintained against a catalogue in another repository, and the first one somebody
forgot to add is the one that would pass. Its own suite breaks it seven ways,
including the failure that would make the other six meaningless: a method parser
that silently matches nothing.
Proven on a live Oxide server: compiled, loaded, the envelope correct, both ban
hooks firing, and the boards repopulating a sidecar whose database had been
deleted 0.3 seconds earlier.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
RunicGateway.cs dials out to a rust-link sidecar on loopback and speaks
newline-delimited JSON over it: server.hello on every connect, a pong to the
sidecar's heartbeat, and one correlated server.status.
The threading contract is the ServUO bridge's, unchanged, because the reason for
it is the same on both games:
* Emit is called from the main thread. It formats nothing, blocks on nothing and
touches no socket -- it enqueues and returns, so a wedged or absent sidecar
cannot stall the game. The queue is bounded, drop-oldest.
* One link thread owns the socket, which keeps event ordering intact.
* A reader thread marshals every inbound line to the main thread through
Interface.Oxide.NextTick, and touches no Unity object, BasePlayer or ConVar.
Settings come from Oxide's own config (oxide/config/RunicGateway.json), so an
operator retunes the bridge the way they retune any other plugin -- and so it
lands inside the site-side config editor a later phase adds.
Four things the live rig corrected, none of which a unit test could have:
* A disconnect was silent in the game console. The teardown log sat in the
catch, and a connection ending because the READER saw EOF leaves the writer to
exit cleanly -- nothing throws, so nothing was logged. A log in a catch only
covers the failures that throw, and an orderly peer shutdown is not one.
* Unload blocked the main thread for 1.9s (Oxide says so out loud), because the
reconnect backoff was Thread.Sleep and Unload joins the link thread. Waiting on
the AutoResetEvent that Unload already signals makes it immediate. The ServUO
plugin has the same sleep and gets away with it only because ServUO does not
hot-reload.
* Mono's SocketException.Message is NUL-padded on Windows -- around 200 \0 bytes
in the middle of the sentence, from a fixed-size OS buffer. \0 is not
whitespace, so Trim does not touch it and neither does a whitespace-only
collapse; the flattener has to treat control characters as separators. It took
od -c on the log to see at all.
* bootId regenerated on every PLUGIN load rather than every SERVER start. A
fresh Guid at Init meant oxide.reload announced a brand new boot, and the
website's reconcile design hangs off that value -- so every reload would have
asked core to sweep its whole resource ledger for a world that never moved. It
is now Process.StartTime: exact, identical on every read, and it changes when
and only when the thing it names changes.
rg.link reports the link's own counters from the console or over RCON, which is
what separates 'the plugin is not loaded' from 'the plugin cannot reach the
sidecar' from 'the website cannot reach the sidecar'.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
The org's standard furniture for a new repo: licence, code of conduct, security
policy, contributing guide, issue and pull-request templates, and the ignore
rules. No plugin yet — that arrives as the first pull request, so this branch
exists to open one against.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
