New cross-node load/store path that bypasses the closed libubsm_sdk.so
entirely and talks to the GPL kernel UAPI /usr/include/ub/obmm.h
directly via ioctls on /dev/obmm.

Background
----------

Scheme 6 (via libubsm_sdk.so) got stuck on daemon-internal error 800
returned from ubsmem_shmem_allocate. The SDK is a binary blob so we
couldn't see what it was actually sending to the kernel. Two earlier
fixes (4MB alignment, real cluster hostnames) were both correct in
isolation but did not unblock 800 — after three iterations it became
clear that the region-based allocation path in the current SDK build
is either broken or requires cluster-side configuration we can't see.

Scheme 7 side-steps the problem by calling the kernel UAPI directly.
obmm.h is 186 lines, GPL-2.0+, and documents exactly the export /
import / unimport / unexport ioctls we need. Corresponding kernel
source lives in openEuler/kernel (OLK-6.6, migrated to AtomGit).

What's in this commit
---------------------

benchmark/engram/scheme7_obmm/
  obmm_rw.h/c  — thin wrapper with four entry points:
                   obmm_rw_open/close
                   obmm_rw_export / obmm_rw_unexport
                   obmm_rw_import / obmm_rw_unimport
                 Plus an 80-byte packed handle struct that carries
                 (mem_id, tokenid, length, uba, seid, deid, scna,
                 pxm_numa, base_dist) across TCP for the cross-node
                 variant that will come next.
  smoke_test.c — single-node loopback:
                   1. open /dev/obmm
                   2. mmap 4 MB anonymous buffer
                   3. write 1 KB pattern
                   4. EXPORT_PID with flags=ALLOW_MMAP
                   5. IMPORT back with flags=ALLOW_MMAP
                   6. read pattern through the imported VA, verify
                   7. quick loopback load-latency bench
                 All seid/deid left zero for the simplest first call.
  Makefile     — plain gcc, no link to libubsm_sdk.so (we verify via
                 ldd that nothing sdk-related sneaks in).
  README.md    — architecture diagram, how to run, expected output,
                 and a "what can go wrong" table tied to each likely
                 EINVAL / EPERM / ENOENT failure mode.

This is Task sgl-project#2 of a 5-task scheme7 plan tracked in the session.
Next tasks:
  sgl-project#3 extend to cross-node via TCP handle exchange
  sgl-project#4 bench scheme7 vs scheme5
  sgl-project#5 integrate winner into SGLang Engram prefetcher

The deferred kernel URMA_SEG_MAPPED patch is documented in
memory/project_kernel_urma_mapped_stretch.md and will be revisited
later as an independent upstream-contribution track — it answers a
different question from scheme7 (API unification, not hardware
capability).

sgl-project#4 18_Q3A_host_tier.sh: adds the missing 4th arm to Q3.A — engine
default MambaRadixCache WITH HiMambaRadixCache host-DRAM tier on
(--enable-hierarchical-cache --hicache-ratio 2.0). Same GSP workload
as 09_setting3a v2 so results are directly comparable to default,
extra_buffer, layer1.

sgl-project#5 19_sweep1_multiseed.sh: single-(ratio, seed) launcher for Sweep 1.
Outer driver fans 3 seeds × 5 ratios across GPUs to characterize
run-to-run variance and put error bars on the 1.91× throughput swing
claim in paper Table 1.

sgl-project#4 Q3.A 4-arm: added host-tier-on row to RESULTS.md table, paper §6.3
tab:q3a updated. Default + HiMambaRadixCache costs 7-11% latency vs
default, reproducing the paper's offload-fetch tax claim.

#2 Setting 4 saturation-blind fix:
- cross_pool_planner.py: new SGLANG_XPOOL_QDEPTH_TRIGGER env var (default
  0 = legacy behavior preserved). When >0, the planner ALSO fires a
  transfer when one pool is saturated (above its high watermark) AND
  queue_depth >= trigger — even if the other pool is above its low
  watermark. Recovers gradient information at saturation.
- agent.py: passes num_queue_reqs to planner.decide(); logs
  xpool_plan_queue_depth in the JSONL stream.
- 35_planner_qdepth_unit.py: 5/5 unit tests pass — qdepth=0 preserves
  legacy, qdepth>0 fires saturation+queue, queue_depth field
  populated.

The fix is gated so existing runs see no behavior change. Sweep 1
multi-seed re-run with the new mode pending (will compare proxy V_kv'
+ V_mamba' decisions across ratios with vs without queue signal).

…ndle_batch_request

Per v2 plan note (2026-05-11). Chapter 5 #1.

The `parallel_sample_num == 1` branch in
TokenizerManager._handle_batch_request has 2 mutually-exclusive sub-paths
gated by `_should_use_batch_tokenization`. Extract each as a sibling
helper:

  - _dispatch_batch_tokenized(obj, batch_size, request) -> (gens, rids)
    batch tokenize all via _batch_tokenize_and_process, _send_batch_request
    once, then per-rid _wait_one_response generators.
  - _dispatch_sequential_tokenized(obj, batch_size, request) -> (gens, rids)
    env-gated input_blocker_guard_region context manager around per-rid
    sequential tokenize → send → wait.

The two paths produce the same (List[AsyncGenerator], List[str]) shape
so the caller rebinds:

  if getattr(obj, "parallel_sample_num", 1) == 1:
      if TokenizerManager._should_use_batch_tokenization(...):
          generators, rids = await self._dispatch_batch_tokenized(...)
      else:
          generators, rids = await self._dispatch_sequential_tokenized(...)
  else:
      # Path B (parallel_sample_num > 1) still inline — Ch5 #2/#3/#4
      ...

The 2 helpers are parallel siblings under the single-sample branch —
lumped in one commit (matches Ch2.1 / Ch4 A1 / Ch4 C2 patterns).
Path B's split into sub-helpers + wrapper is the next 3 commits.

Adds `AsyncGenerator, Tuple` to the typing import.

No behavior change. Helper bodies preserve the original control flow and
side-effect order. The pre-existing `generators = []; rids = []` init at
the top is annotated with explicit types and remains for Path B's
inline body (which still appends).

Refactor chain ID: extract-single-sample-dispatchers

Per v2 plan note (2026-05-11). Chapter 5 #3.

Path B's expand-requests loop generates parallel_sample_num copies per
obj (each with a freshly regenerated rid), inits state for each, sends
each via _send_one_request, and accumulates _wait_one_response generators.
After the inner expansion finishes for one obj, it marks the original
rid's time stats as finished and pops it from rid_to_state.

Extract this loop into _expand_parallel_sample_requests, which returns a
fresh (generators, rids) tuple. Caller rebinds locals:

  generators, rids = self._expand_parallel_sample_requests(
      objs, tokenized_objs, obj.parallel_sample_num, request,
  )

The helper is sync (no awaits inside — _send_one_request is sync;
_wait_one_response returns the async generator, not awaited here).

The per-obj sequencing is preserved: the inner expansion loop runs
parallel_sample_num iterations BEFORE the original rid is popped, so
expanded children always see the prefix's cached state during their
own _send_one_request call.

Path B's outer wrapper (warn + asyncio.gather + #2 + #3) is the next
commit (Ch5 #4).

No behavior change. The copy.copy(...) + regenerate_rid() + init_req +
time_stats threading + send + append + pop sequence is byte-identical
to the original inline form.

Refactor chain ID: extract-expand-parallel-sample-requests