feat: {.ffiHandle.} — export complex live objects as opaque handles

[gmelodie]

Summary

Implements #80. Adds {.ffiHandle.}, letting an .ffi. proc return — or receive — a complex, non-CBOR-serializable live object (a Waku, a Kernel, a session) by reference instead of by value.

The object never crosses the FFI boundary. Its wire form is a plain uint64; the live ref lives in a per-ctx registry and is reconstituted on the way back in. A given type is either a value type ({.ffi.}, copied) or a handle type ({.ffiHandle.}, referenced) — never both — so there is no per-proc "send the object vs send a handle" choice.

type Kernel {.ffiHandle.} = ref object
  ...

proc demoKernel*(d: Demo, req: MakeReq): Future[Result[Kernel, string]] {.ffi.}   # returns a handle
proc demoKernelSend*(k: Kernel, msg: string): Future[Result[string, string]] {.ffi.}  # handle is the receiver

Design

• ffi/ffi_handles.nim — FFIHandleRegistry, mirroring the FFIEventRegistry idiom: monotonic nextId (0 = null, ids never recycled) + a Table. register / lookup / release / releaseAll. Each entry records its type name, so a stale, forged, or wrong-type id misses cleanly → RET_ERR, never a use-after-free. Single-threaded (FFI-thread) access, so no locking. Handle types inherit an injected FFIHandleRoot base so heterogeneous refs are storable under one static type.
• FFIContext — new handles field, init/deinit alongside eventRegistry. Refs are freed on the FFI thread (ffiThreadBody defer) because refc heaps are thread-local.
• Macro forks in ffi/internal/ffi_macro.nim:
  • ffiHandle type macro — validates ref object, injects of FFIHandleRoot, records the name.
  • storageType — a handle param stores as uint64 in the per-proc Req.
  • Return path — a handle return is registered; only the id is CBOR-encoded.
  • Param path — a handle param is lookuped, returning RET_ERR on a miss.
  • First-param (receiver) fork — a handle receiver resolves FFIContext[LibType] / pool from the lib type recorded by declareLibrary.
  • Composes with {.ffiRaw.} with zero special-casing: the wire type is already uint64, so raw bodies call ctx.handles.lookup/register/release by hand.
• Codegen (rust / cpp / cddl) — handle params and returns map to u64 / uint64_t / uint; no struct is emitted for a handle type. The flat kernel_send(ctx, handle, …) form works; the optional OO/RAII wrapper class is left for a follow-up.
• declareLibrary now also declares the <LibType>FFIPool var (previously only ffiCtor/ffiDtor did) and records the lib type name.

Testing

• tests/unit/test_ffi_handle.nim: handle round-trip (out as uint64 → reconstituted live object), handle-as-receiver, and forged / null id → RET_ERR. Passes under orc and refc, and is ASAN/UBSan-clean.
• Existing suites pass; the timer/echo example bindings regenerate unchanged (no codegen regression); nph --check clean.

[Ivansete-status]

LGTM! Thanks for it! 💯