feat(node-cxx): memory-pool transport with a CUDA-IPC-free path for integrated GPUs

[caothu2k1]

Closes the remaining half of #2686. The Service/Action half landed in #2853.

The problem

apis/python/node/src/lib.rs:2308 fails registration when a CUDA receiver's IPC
export fails:

if receiver_is_cuda && !ipc_written {
    eyre::bail!("register_memory_pool: failed to set up GPU pool buffer / IPC handle …");
}

On an integrated GPU cudaIpcGetMemHandle is unsupported, so that branch always
fires. Today no language binding can use a CUDA receiver on such a device —
the memory-pool transport is unavailable there entirely, not merely slow.

What this adds

A third transport, unified. Full shared-memory data region, ipc_flag = 0;
the receiver takes a device alias of the same pages with
cudaHostRegister(..., cudaHostRegisterMapped) + cudaHostGetDevicePointer. It
needs no protocol change because it reuses the existing segment layout, and it
works on every platform — on a discrete GPU it is merely slower than ipc.
auto resolves to unified when the receiver is CUDA and shmem otherwise, so
it can never resolve to a mode that fails at registration.
DORA_MEMORY_POOL_TRANSPORT overrides auto and nothing else.

The DORADMA data plane gains a definition in dora-memory-pool. The header
layout, the seqlock and the segment lifecycle previously existed only as
hand-written byte offsets inside the Python binding. This adds a tested
implementation the C++ binding builds on — it does not consolidate: the
Python binding still carries its own hand-written copy, and making it the single
definition is follow-up work.

The C++ binding gains the pool surface: register_memory_pool,
write_memory_pool, read_memory_pool, free_memory_pool, plus the pointers a
producer needs to fill a pool in place instead of paying a second copy.

Two optional header-only C++ helpers. dora/memory_pool.hpp provides
PoolWriteGuard and PoolReadGuard; dora/cuda_pool.hpp provides the mapping
helper. No Rust crate links CUDA — the language side owns it, matching how the
Python binding already works.

Design notes a reviewer may want

Invariants live in the types, not in doc comments. FFI is where Rust's
enforcement stops, so several review rounds moved guarantees across that line:

• Payload access is pool_payload(&mut ptr, &mut len) -> bool, an out-param
  predicate returning false for an ipc pool. An earlier shape exported a
  pointer and a length that did not bound each other: on an ipc pool the
  offset points one byte past the mapping while the declared size reports
  megabytes, so memcpy(host_ptr(), src, size()) — the natural C++ line — wrote
  megabytes out of bounds. There is no declared-size accessor on the C++
  surface at all.
• No generation token crosses the bridge. It lives in the segment, so a
  fabricated value cannot publish a torn frame as complete.
• begin_read returns an opaque OpeningSample that is deliberately not
  PartialEq, and the closing comparison lives inside read_completed. Closing
  a read with a second opening sample loads the same value with the wrong fence,
  so it passes every test while admitting torn frames on a weakly-ordered CPU —
  the type system is the only thing that can catch it.
• PoolWriteGuard is the documented write path. A caller that returns early or
  throws between begin_write and end_write leaves the generation odd
  permanently and the pool unreadable to every consumer; there is no Drop on
  the Rust side to recover it.
• dtype and shape are advisory metadata, never a bound. An unrecognized
  dtype is assumed one byte, so a shape-derived product under-estimates.
  payload_len is the only bound.

Seqlock ordering. A reader needs two different edges — gen load → payload loads when opening, payload loads → gen load when closing. An acquire load
gives only the first. read_completed therefore pairs an acquire fence before
a relaxed load. Accesses go through AtomicU64::from_ptr rather than
read_volatile plus a bystander fence, so the code is correct under Rust's
memory model rather than only under inspection of the emitted barriers; the
shared-memory representation is unchanged.

One deliberate divergence to flag, since the extracted code is meant to match
what it was extracted from: the writer fences before the generation store,
while seqlock_end in the Python binding (apis/python/node/src/lib.rs:1070)
has its only fence(Release) after it. The pre-store fence is the one that
orders the payload writes ahead of the publish, so without it a weakly-ordered
target can publish an even generation whose payload is not yet visible. The
Rust version is stronger on purpose. The Python path is untouched here — this
change does not modify that binding — but it is worth a separate look.

Verification

Unit — 85 tests in dora-memory-pool, 53 in dora-node-api-cxx. Every
DORADMA constant is pinned against the Python binding's own values. Each check
was mutation-tested: the guard was deleted, the targeted test confirmed red for
the right reason, the guard restored. Where a mutation could not be killed it is
recorded in a comment rather than left implied.

In CI — examples/c++-memory-pool runs the whole path over a live daemon on
the CPU: a 16-slot ring filled in place through the guard, both read paths, an
abandoned write cycle rejected and then recovered, and a freed pool going
permanently unreadable while a second pool still reads. Registered in
tests/example-smoke.rs, scripts/smoke-all.sh and the nightly examples job.
The runner fails if any dora_pool_* segment survives.

Its run.rs passes -l dora_node_api_cxx before the system libraries, unlike
the neighbouring C++ example. That order is required: GNU ld resolves an archive
only against what follows it, so the other order leaves dlopen/dlsym
undefined on any glibc older than 2.34. It happens to link on ubuntu-latest
because libdl is folded into libc there.

On device — a Jetson (JetPack 5, CUDA 11.4), integrated GPU:

[cuda-receiver] transport=unified ipc_present=false integrated_gpu=true
[cuda-receiver] registered 16896 bytes of `frames`: host=0xffff… device=0x2031…, payload at +512
[cuda-receiver] 21 frames verified through the device alias, 1 torn, 1 unavailable

A kernel reads bytes the host wrote, through the device alias, with no
intervening copy — the only two cudaMemcpy calls move a 12-byte verdict, never
the payload. The mapping is registered once at startup, before any frame exists,
and 21 frames of changing content then arrive through that same never-refreshed
alias, so it cannot be a snapshot taken at registration time. Substituting the
host pointer for the device alias faults rather than passing, because the two
are genuinely different addresses on this hardware.

Cross-language — a pool registered by the untouched Python binding is
read by a C++ node, on the CPU path and from a kernel through the device alias.
Note the precise claim: the two are not byte-identical. A Python CPU pool
writes no transport key, writes pinned_type: "cpu" where a C++ unified
pool writes "cuda", uses json.dumps spacing so json_len differs, and lands
at write_gen = 2 where create leaves 0. They interoperate because the
consumer reads every one of those fields out of the header instead of
assuming them — which is the real argument, and a better one.

Not in this PR

• The Python binding is unchanged. A Python sender with
  receiver_device="cuda" still fails on an integrated GPU. Follow-up: teach
  its auto-select about unified, and move its data plane onto the shared
  crate.
• The C++ binding does not produce ipc pools — that would require CUDA
  inside the binding. It reads one and hands out the handle.
• The pool's daemon parameters are still hand-mirrored.
  MemoryPoolMetadata lives in dora-memory-pool, but its MetadataParameters
  conversion is private to dora-daemon, so the binding transcribes nine keys
  and pins them with a test against a copy of the daemon's reader. Moving that
  conversion next to the type would delete the transcription at the cost of a
  dora-message dependency.
• The CUDA example and the Python-interop CUDA dataflow are manual, hardware-
  gated artifacts; only the CPU paths run in CI.

🤖 Generated with Claude Code

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[phil-opp]

🤖 Automated review by Claude Code — fully automated review, not vetted by a human.

No issues found.

I reviewed the data-plane crate (seqlock.rs, doradma.rs, segment.rs, naming.rs), the C++ binding FFI, and the shipped C++ headers, focusing on the parts a seqlock/FFI transport tends to get wrong:

• Seqlock ordering — the closing read correctly uses an acquire fence before a relaxed load (not a second acquire load), begin_write fences after marking the generation odd, and the leftover-odd recovery path lands back on an even baseline. OpeningSample/DoraPoolRead are opaque across the bridge so a caller can't forge or mis-fence a token.
• Bounds — header_region_len caps the header slice at data_offset (never at segment_len), the ipc_flag/transport contradiction is rejected before the size check can be skipped, and offset arithmetic saturates/checks. payload() returns None for ipc rather than a one-past-the-end ptr with a large length.
• Free/liveness race — mark_freed flips the flags under the registry mutex with Release/Acquire pairing before the ids reach C++, read tokens are serial-bound to their issuing view, and the mapping is deliberately not unmapped on free, so a racing read is not a use-after-free.
• Naming — component charset + explicit .. check on construction, and validate_segment_name re-guards prefix///.. at the unlink point for names arriving from a peer.

The tests exercise real behavior (specific error substrings, adversarial headers, cross-language segment shapes) rather than tautologies. Given the size and the unsafe/FFI surface, a human pass over the memory-ordering and the C++ header lifetimes is still worthwhile before merge.

---

Generated by Claude Code

[phil-opp]

Two things worth fixing before this lands, neither blocking the design.

Data race on the seqlock generation. segment.rs:360 / doradma.rs:386 form a &[u8] over the header region (HEADER_SIZE + json_len, so >=256 bytes). That span includes byte offset 96 — the seqlock generation a peer writer stores to via AtomicU64 — and it is read with read_u64. That is exactly the race the payload path takes care to avoid, and the comment at segment.rs:346-348 ("written once, before the pool is registered") is not true for those 8 bytes. ParsedHeader.write_gen is never read anywhere in the workspace, so dropping the field removes the race for free (otherwise load it through AtomicU64::from_ptr).

free_memory_pool can strand a segment. apis/c++/node/src/lib.rs:1790 refuses when a write cycle is open, but the Box<DoraMemoryPool> is consumed regardless — so after the refusal the caller has no handle left to close the cycle or retry. Net effect of the "safe" path is a segment left in /dev/shm and in the daemon's table for the rest of the dataflow. Returning the box on refusal would make it actionable.

Minor: DORA_MEMORY_POOL_TRANSPORT="" hits the Some(other) arm and hard-fails instead of being treated as unset (lib.rs:1488); and the nightly uv venv step writes VIRTUAL_ENV to $GITHUB_ENV, which applies to every subsequent step in the examples job, not just this one.

For the record, I read the memory ordering closely and it is correct — relaxed odd-store plus fence(Release) is the right formulation, and making OpeningSample opaque and non-PartialEq genuinely prevents the close-with-a-second-begin_read bug.

[caothu2k1]

Thanks — all four verified at the source and fixed in 4354a25. Three are fully closed; the first is closed only in part and I'd rather say so than let it read as done.

Seqlock read race. Confirmed: parse_header decoded write_gen with a plain read_u64 out of a span a peer writer stores to atomically, and the field's only consumer in the workspace was a test assertion. Dropped the field and the read. Every generation access already went through gen_ptr() as an AtomicU64, so nothing else changed.

You were also right that the justification comment was false for those 8 bytes, and that is the part still open. Dropping the field removes the read, but the &[u8] still spans offset 96, and by the standard that comment itself sets — UB whether or not anything reads through the reference — that is not yet clean. Narrowing it properly means passing the fixed header and the JSON as two slices; conveniently every fixed field parse_header decodes lives below offset 96, so 0..96 plus the JSON region covers it with nothing left aliasing the generation word. That touches parse_header's signature and 19 test call sites, so I did not fold it into a PR you are mid-review on. The comment now states the residual plainly instead of claiming the span is write-once. Happy to do the split here or as a follow-up — your call.

Strandable free. This one was a regression I introduced, and your reading of it is exactly right: the refusal landed in a late review round, and I added the guard without following what happens after it fires. The box was consumed regardless, so the "safe" path guaranteed a leak where the unguarded path merely risked one. It borrows now, so a refusal leaves the caller the handle to close the cycle and free properly. The example's release() was the only call site.

Empty env var. Fixed. Worth noting the test that covered it asserted the defect — it listed "" among the values that must be rejected — so correcting the behaviour turned it red. It now asserts that clearing the variable restores the default.

$GITHUB_ENV. Scoped to the step that needs it.

Gates green after the change: fmt, workspace clippy -D warnings, 87 + 56 unit tests, cargo check --examples, and the CPU example end to end on a live daemon (11 copied, 10 zero-copy, 1 torn, 1 unavailable, /dev/shm clean).

And thank you for reading the ordering closely — that is the part I most wanted a second pair of eyes on, and knowing the relaxed-store-plus-release-fence formulation and the OpeningSample opacity hold up is worth more than the rest of the review combined.