@spec signal_nif_reload!(String.t()) :: :ok

Signal the Hourglass.Subsystem :rest_for_one cascade by exiting Hourglass.Runtime with :nif_reloaded. Public so BridgeHolder (which has its own retry/recycle semantics around worker handles and cannot simply return {:error, :nif_reloaded} from every call shape) can share the same signal path as the generic with_nif_reload_rescue/2 wrapper.

call_site is logged at :error level for post-mortem attribution.

@spec with_nif_reload_rescue(String.t(), (-> result)) ::
  result | {:error, :nif_reloaded}
when result: term()

Wrap a Bridge NIF call so a post-hot-reload ArgumentError (from a stale resource ref decoded against a freshly loaded NIF resource-type registry) cascades a Hourglass.Subsystem restart instead of bubbling up as an opaque crash.

fun is a zero-arity function that performs the NIF call. On success, its return value is propagated unchanged. On ArgumentError, the helper:

1. logs the call site at :error level,
2. signals Hourglass.Runtime to exit with :nif_reloaded (which cascades the rest of the :rest_for_one subtree — BridgeHolder, WorkerRegistry, Worker.Supervisor, WorkerLauncher — so every pre-reload resource ref is dropped and re-acquired against the freshly loaded NIF), and
3. returns {:error, :nif_reloaded} so callers' with chains unwind cleanly.

The rescue is intentionally narrow: only ArgumentError, not rescue _. Widening would silently catch real argument bugs at the Bridge boundary.

No automatic retry inside the helper: the cascade is async and the caller's process may itself be killed by the cascade (e.g. if the caller is BridgeHolder). A second NIF call from the same caller would re-raise ArgumentError, which the helper handles identically; Process.exit/2 on a now-dead Runtime pid is a no-op, so there is no loop hazard, but there is also no point in adding a built-in retry. Callers that want one (e.g. Replayer.replay_history/2, which is a stateless one-shot) wrap a fresh Runtime.handle() + call themselves.

Use this helper for any new Bridge call site that allocates or operates on a resource ref from process-lifecycle code paths.