feat(ffi): experimental reverse FFI — host-implemented plugin interfaces ({.ffiReverse.} / {.ffiReverseEvent.})

[NagyZoltanPeter]

Closes #153

Experimental reverse FFI: a library can declare interfaces the host fulfils at runtime (plugin/SPI direction), and event handlers the host emits into. Design and phase-by-phase plan: REVERSE_FFI_PLAN.md (option B — delivery on the event dispatch thread, async any-thread reply ABI).

What's in here

Pragmas

# Host-implemented interface: bodyless, awaited from any {.ffi.} handler.
proc fetchHostClock(precision: string): Future[Result[HostClock, string]] {.ffiReverse.}

# Host-emitted event: the body is the handler, run on the FFI processing thread.
proc onHostTick(tickNo: int) {.ffiReverseEvent.} =
  lastHostTick = tickNo

Runtime (ffi/ffi_reverse.nim + thread wiring)

• The caller stub CBOR-encodes args, parks a chronos future keyed by a monotonic call id, and rides the existing event ring (QueuedEvent gains a kind; ekListener = 0 keeps zero-init paths intact). The FFI processing thread stays free while the call is parked.
• The host impl is invoked on the event dispatch thread (registry mirrors the event registry's snapshot-dispatch/wait-out semantics; set_impl(NULL) unregisters and waits an in-flight invocation out).
• Replies come from any host thread via <lib>_reverse_reply: c_malloc'd CBOR into an intrusive mailbox, woken through the existing reqSignal (no extra ThreadSignalPtr — refc cannot close them), decoded on the FFI thread's own heap. No Nim ref ever crosses a thread boundary; behavior is identical under refc and orc.
• Mandatory deadline per call (ReverseCallTimeoutMs, per-proc {.ffiReverse("wire", timeout = ms).}); unfulfilled interfaces fail fast; late/stale replies are dropped by call-id lookup.
• Recycle/shutdown fail parked reverse calls before the drain, so a handler awaiting the host cannot hold drainOngoing until its deadline and trip the fix(ffi): quarantine a context whose {.ffiDtor.} did not finish #151 DrainTimeout quarantine.
• {.ffiReverseEvent.} is sugar over the one-way request path: generated <lib>_emit_<wire> enqueues a fire-and-forget request; the return code reports the enqueue only.

C bindings (CBOR ABI)

Raw exports plus typed ctx-wrapper sugar: _ctx_set_<wire>_impl, _decode_<wire>_args, _ctx_reverse_reply_<wire> (payload-less for void replies), _ctx_reverse_reply_err, _ctx_emit_<wire>. An abi = c library with reverse declarations fails C binding generation loudly.

Example + docs

examples/timer gains fetch_host_clock / on_host_tick with driver methods; all four binding sets regenerated. README documents the pragmas and a semantics table; CHANGELOG entry added.

Verification

Check	Result
nimble test (all unit tests, orc + refc)	60 binaries green, 0 failures
New unit tests (test_ffi_reverse_state, test_ffi_reverse, test_ffi_reverse_macro)	23 tests: state, ring, timeout, late-reply drop, recycle-with-inflight, generated exports end-to-end
test_c_codegen	+7 reverse header assertions
nimble test_c_e2e	C host: typed args decode + inline reply on the dispatch thread, fail-fast, unregister, reverse event
nimble test_cpp_e2e, nimble check_bindings	green
ASAN+UBSAN and TSAN, orc × refc, on the three reverse test files	clean

Note: test_event_dispatch fails under ASAN+orc identically on master (cross-thread table dealloc in deinitEventRegistry; possibly the local mixed-toolchain setup) — pre-existing, untouched here.

Out of scope (follow-ups)

cpp/rust/cddl reverse codegen, abi = c wire shape for reverse, {.ffiHandle.} params in reverse calls, host-side cancellation, re-entrant reverse calls from inside an impl.

🤖 Generated with Claude Code