P1-B: BufferHandle memory-model ABI + user-facing Tensor cutover

[YunjiQin]

P1-B: BufferHandle memory-model ABI + user-facing Tensor cutover

Replaces the legacy "raw pointer + child_memory bool" L3+ memory mechanism with a typed,
self-describing BufferHandle ABI, and flips the live L4→L3 / L3→L2 / L3→SUB dispatch wire from
address-carrying tensor blobs to identity-carrying ones.

The user-facing argument type stays named Tensor at every level — handle.tensor(shapes, dtype),
args.add_tensor(t, tag). What changed underneath it is what a Tensor carries: a canonical
identity plus a BufferHandleDescriptor, instead of a raw address and an is_child flag. BufferRef
is the C++ wire struct's name and does not appear in user code; the chip-side POD keeps its own name,
ChipTensor, and stays internal to the L2 runtime.

User guide: docs/buffer-handle-abi.md — including the
"Why Tensor and ChipTensor are two types" section, which is the design question a reviewer is most
likely to raise (field-by-field, with the two rejected unifications and why).

Please review commit by commit. The diff is large, but each commit is self-contained and
ordered so the wire ABI lands before its consumers. Reviewing the squashed diff loses that order.

Commits (read in order)

1. Add the BufferHandle/BufferRef memory-model ABI + owner create_buffer — wire types
   (child_memory→address_space), versioned blob codec, owner BufferHandle + ImportRegistry
   (lazy map-once by canonical identity), self-describing refs, FORK_SHM COW base VA,
   Worker.create_buffer.
2. Flip the live dispatch wire; three-way consumer split; device/remote/strided —
   TaskArgs carries the new wire element through the C++ dispatch; infer_deps keys on canonical
   identity; chip → materialize → run_from_blob, sub → MappedArg (torch.frombuffer), L4→L3 →
   re-export; DEVICE_MALLOC + REMOTE_SIDECAR + strided materialization.
3. Resource APIs + ABI doc + cpput migration; remove TensorTaskArgs; L2 in-process materialization —
   alloc_shared_tensor / alloc_child_tensor; migrate the C++ GoogleTest suite; fold TensorTaskArgs
   onto ChipStorageTaskArgs; uniform L2 in-process materialization.
4. Move device-memory ownership from Orchestrator to Worker — malloc/free/copy_to/copy_from/
   alloc_child_tensor live on the Worker (keyed by owner_worker_id); orch.* are thin forwards; the
   raw-pointer orch.malloc / orch.device_handle are removed.
5. Comm-domain VMM_WINDOW buffers; migrate examples & scene tests — a memoized FORK_SHM handle over
   a pre-fork host tensor; allocate_domain hands back VMM_WINDOW BufferHandles
   (domain.buffers[name].ref); migrate every collective / demo / L2-L3 example and the scene-test
   framework.
6. ChipStorageTaskArgs chip-only; delete create_host_buffer; sub scalars; orch.alloc→handle —
   ChipStorageTaskArgs is the chip-only POD (ChipWorker._run_slot); Worker.run at L2 takes a
   TaskArgs/None; delete the create_host_buffer/MAP_HOST subsystem (superseded by
   create_buffer + lazy import); sub callables receive scalars; orch.alloc returns a BufferHandle.
7. Capability matrix + access⊆granted dispatch guards — reject an unsupported
   address_space × backend_kind on both owner construction and wire decode; reject an argument whose
   TensorArgType needs access the handle does not grant.
8. Slim the buffer ABI, validate it, and stage host copies — CanonicalIdentity 96→32 B,
   BufferRef 272→144 B; the owner worker path leaves the identity and becomes a diagnostic
   owner_worker_path_id that takes part in no routing decision; one shared validate_buffer_ref at
   the three boundaries that accept untrusted bytes (builder, blob decode, materialization); a
   DEVICE-space tensor bound for a Python sub-worker is refused at submit; control-plane copies stage
   through a POSIX shm instead of sending a host address across the fork (a host BufferHandle
   transfers by name with no intermediate copy). Also fixes an out-of-bounds table read in
   get_element_size reachable from the wire.
9. Submit-time argument guard and a copy-on-write backend tag — re-check access ⊆ granted where
   the values are final (a tag stays mutable after add_tensor), and reject two arguments of one task
   that name intersecting bytes of one backing — nothing downstream can catch that pair. Split the
   fork-inherited backend into FORK_SHM / FORK_COW so the decoder can enforce that a
   copy-on-write page grants READ only. Also fixes a stale handle-memo hit when the allocator reuses a
   storage address at a different size.
10. Rename Worker.make_ref_arg → make_tensor_arg — the last place the wire type's old name
    reached user code.

Verification

• a2a3sim: 43 scene tests — allreduce collective ST corpus + L2/L3 examples (allreduce,
  domain_rank_map, dual_domain_overlap, ffn_tp_parallel, async/deferred notify, vector_add,
  create_buffer, child_memory, l3_dependency/group, dynamic_register) — golden 0.
• onboard a2a3 (Ascend910): L3→L2 chip dispatch, mixed host+device, L4→L3→sub re-export,
  sdma_async_completion.
• pyut: 938 passed, 2 skipped.
• cpput: 67/67 (no-hardware subset).
• ruff / pyright / clang-format / cpplint / markdownlint clean; every commit passes the pre-commit gate.

Two bugs the new validators caught in existing code, both true positives: a scene-test fixture holding
a 16×int32 view at offset 4 in a 64-byte backing, and a C++ make_ref() that never set
handle.nbytes.

Rebased onto current main. Three of the landed changes interact with this branch and are folded into
the commits that own them, not bolted on at the tip: the launch-acceptance fence's extra run_from_blob
arguments now ride the materialized blob; interior copy_to/copy_from ranges keep their
allocation-extent check after the ops moved onto the Worker, so a BufferHandle's recorded extent is
what admits a partial update; and the depth-two pipeline-slot tests build Tensor args for
Worker.run while keeping the runtime.so-ABI POD for the direct-lease path.

Remaining (follow-ups, not in this PR)

• Buffer lifecycle: release_buffer, in-flight retain / deferred free, generation bump on slot
  reuse, and dropping an import mapping with its handle.
• P2 (remote): the send side (RemoteTaskArgsWire) still carries chip-tensor metadata over the
  wire; full remote e2e. REMOTE_SIDECAR materialization stays reserved for P2.
• Heap separation (SharedBufferArena): alloc_shared_tensor is the interim runtime-managed
  intermediate; the dedicated arena is a follow-up.
• Dependency-key precision: identity-keyed infer_deps deliberately keeps the same behavior as
  today's L3 + TensorMap mainline; tightening it is out of scope here.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c60163b2-5eac-467e-a8fd-7507132696e0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}