Add: the Buffer/Tensor wire ABI and owner-side create_buffer

[YunjiQin]

The buffer ABI: how L3+ tasks name their data

At L3 and above a task argument is a raw pointer plus a child_memory bool, so the receiver has to
guess what it was handed. This lands the typed, self-describing replacement — a canonical identity, a
backend descriptor, and a strided view — which together let a consumer resolve a buffer exactly
across the L3→L2 and L4→L3 boundaries with no side table and no address rewriting.

User guide: docs/buffer-abi.md, including the
"Why Tensor and ChipTensor are two types" section with the two rejected unifications.

Nothing dispatches a Tensor yet — TaskArgs still carries the device POD — so this is
behavior-neutral. It lands on its own because the byte layout is frozen once it ships, and it should
be read in its own context rather than inside the cutover that consumes it.

What lands here

src/common/task_interface/buffer.h	3 wire types + validate_buffer_descriptor / validate_tensor + tensor_extent_bytes / tensors_overlap, every offset and size pinned by static_assert
python/bindings/task_interface.cpp	those 3 types and their 3 enums bound directly
python/simpler/buffer.py	Buffer (owns a POSIX shm), the wrap_* constructors, ImportRegistry (map-once by canonical identity)
python/simpler/worker.py	Worker.create_buffer, released through the retryable cleanup journal

Three types. Buffer is an owned backing with a lifecycle, which stays with the Worker that created
it. Tensor is the argument a user builds and submits: the buffer descriptor embedded whole, plus a
view, and no address — at submit time none exists, since a POSIX_SHM backing maps to a different VA
in every process and a DEVICE_MALLOC one is valid only on its owner chip. ChipTensor is the POD the
L2 runtime ABI reads, which must carry an address because the kernel dereferences it.

Naming — the model from #1676 / #1681

Worker domain:  Tensor      — address-free, cross-edge logical view
Chip domain:    ChipTensor  — materialized GM-address-bearing POD

Rebased onto #1681, which moved the device POD off the global Tensor name. That is what frees the
plain name for the L3+ type, so Buffer and Tensor are global in C++ and spelled identically in
Python — no namespace, no per-language alias, no second public meaning for Tensor.

TENSOR_STRIDE_BYTES and TENSOR_CHILD_MEMORY_OFFSET, which describe the device POD, become
CHIP_TENSOR_STRIDE_BYTES / CHIP_TENSOR_CHILD_MEMORY_OFFSET so they cannot be read as belonging to
the wire type exported beside them.

Bound, not mirrored — and no bytes cross the binding

CanonicalIdentity, BufferDescriptor and Tensor are the C++ structs bound directly rather than a
Python re-encoding of the same bytes: one layout definition instead of two, one validator instead of
a full one and a weaker one. Buffer and ImportRegistry stay Python — they own a SharedMemory
and a process-local mapping cache, neither of which is ABI.

The types expose their fields and not their encoding: there is no pack() / unpack(). Python
builds a Tensor and receives one already decoded, and the sole path from wire bytes to a Tensor
runs inside C++. Withholding the encoding is what keeps validate_tensor a gate rather than a
habit — a second way in is a second thing to remember to validate on.

Measured on the receive path, decoding a 4-tensor blob into objects: 37 µs → 0.44 µs.

No second transport

A Tensor rides the TaskArgs mailbox blob that write_blob / read_blob already implement in
task_args.h. The cutover swaps that blob's element from ChipTensor to Tensor and moves
TaskArgsView with it, leaving ChipTensor only in ChipStorageTaskArgs. A second blob codec
beside the existing one would be the same structure twice, so this PR ships the types and their gate
and leaves the wire where it is.

Cutover note. TaskArgsView::tensors(i) does not validate today, which is correct while the
element is a ChipTensor — an address plus a shape has no wire invariant a decoder could test. The
flip must add validate_tensor(t) there, because Tensor does have invariants and this PR
deliberately leaves no other way in.

Tensor is foundation-only until the wire flip

TaskArgs.add_tensor still takes a ChipTensor, so Tensor lives in simpler.buffer and is not
re-exported from simpler.task_interface. A public type whose own submit call rejects it is worse
than no public type; it joins that module in the cutover that makes TaskArgs carry it.

test_wire_tensor_stays_off_the_public_submit_surface pins the two facts to each other — whichever
moves first fails until the other follows.

A latent defect, found and fixed

ImportRegistry keyed on identity.pack(), and pack() emitted _pad, which defeats the
padding-insensitive equality and hashing the model rests on: two decodes of one backing landed in two
registry entries, so map-once silently did not hold. Caught with a failing repro first. The registry
now keys on the identity itself; with pack() gone the mistake is no longer expressible at all,
which is a stronger guarantee than the regression test it replaces.

Today the padding is zero end to end, so this is latent — it becomes real the moment the cutover puts
descriptors on a live mailbox.

What is deliberately NOT here

• The wire flip. TaskArgs still carries the device POD, so buffer.tensor(...) has no consumer
  and the submit-time checks the doc describes are not reachable.
• The other allocators (alloc_shared_tensor, alloc_child_tensor), device-memory ownership moving
  onto the Worker, comm-domain VMM_WINDOW buffers, and the example/scene-test migration.
• ChipTaskArgs<ChipTensor> naming at the chip boundary (Support: define layered runtime naming #1676 point 4). Worth flagging for whoever
  picks it up: ChipTaskArgs is already taken by the device-side orchestration arg in
  src/{arch}/runtime/*/pto_types.h, while the host-side type is ChipStorageTaskArgs.

Verification

• Build green — all four arch×runtime C++ trees plus the nanobind extension
• pyut — 1131 passed, 6 skipped
• cpput — 81/81 (no-hardware subset); test_buffer is 13 cases, including field-by-field
  decode rejection, a fixed-seed 4096-iteration arbitrary-bytes pass, and padding-insensitive
  identity keying
• pre-commit green (clang-format / clang-tidy / cpplint / markdownlint / ruff / pyright)
• a2a3sim and a5sim full scene suites rc=0 on the immediately preceding revision; re-running
  on this one (the delta since is binding surface, tests and docs only — no runtime path)
• Hardware (onboard) — not run

The malformed-bytes cases live in tests/ut/cpp/types/test_buffer.cpp rather than Python, because
with no unpack() those states cannot be built from Python at all — which is the point.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

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: 87a45cff-7e2d-42ec-a831-f675a462a7e7

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

📝 Walkthrough

Walkthrough

Introduces a typed BufferHandle and tensor-view ABI with canonical identities, backend descriptors, validation, blob serialization, Python materialization, worker-owned shared-memory allocation, bindings, documentation, and C++/Python tests.

Changes

BufferHandle ABI

Layer / File(s)	Summary
ABI contracts and documentation src/common/task_interface/*, docs/*, mkdocs.yml, tests/ut/cpp/*	Defines fixed-layout identities, descriptors, tensor views, backend tags, validation rules, blob codecs, shared datatype constants, documentation, and ABI-focused tests.
Python packing and materialization python/simpler/buffer_handle.py, python/bindings/task_interface.cpp, tests/ut/py/test_buffer_handle.py	Adds Python wire-format types, handle constructors, shared-memory and pointer-backed materialization, blob helpers, bindings, and decode/runtime validation tests.
Worker allocation and teardown python/simpler/worker.py	Adds Worker.create_buffer, per-worker identity tracking, owned-handle registration, and shared-memory cleanup during teardown.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• hw-native-sys/simpler#1473: Updates related DataType element-size lookup and task-interface ABI plumbing.

Poem

A rabbit hops through shared memory bright,
Naming each buffer with identity right.
Strides curl softly, blobs cross the way,
Workers clean handles at close of day.
“Nibble the ABI—hooray!”

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 32.26% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the Buffer/Tensor wire ABI and the owner-side create_buffer API, which are the primary changes.
Description check	✅ Passed	The description covers the same Buffer/Tensor ABI and create_buffer objectives, although several file names and implementation details do not match the summarized changes.

---

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.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (2)

tests/ut/cpp/types/test_buffer_handle.cpp (1)

71-82: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

EnumValuesAreFrozen doesn't pin BackendKind::FORK_COW.

Every other BackendKind value (0-4) is checked here but FORK_COW = 5 is missing, even though the test's stated purpose is to "pin the sizes, enum values, and the blob codec from the outside". Trivial to add for parity with the rest of this test.

✅ Proposed addition

     EXPECT_EQ(static_cast<uint8_t>(BackendKind::DEVICE_MALLOC), 4);
+    EXPECT_EQ(static_cast<uint8_t>(BackendKind::FORK_COW), 5);
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/ut/cpp/types/test_buffer_handle.cpp` around lines 71 - 82, Add an
assertion in BufferHandleAbi.EnumValuesAreFrozen that verifies
BackendKind::FORK_COW converts to uint8_t value 5, preserving the existing
checks for BackendKind values 0–4.

src/common/task_interface/buffer_handle.h (1)

313-328: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

BufferRefBlobView::ref(i) has no bounds check on i.

ref(i) memcpy's sizeof(BufferRef) bytes at ref_bytes + i * sizeof(BufferRef) with no check that i < ref_count (or i >= 0). Current callers (bufferref_blob_descriptors/refs/scalars in task_interface.cpp) all loop i < view.ref_count, so this isn't exploitable today, but the function is documented as the single shared extraction point for three receive boundaries, so a future caller passing an unchecked index would read out of the validated region.

Optional: add an i < ref_count assert/throw inside ref() itself for defense-in-depth.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/common/task_interface/buffer_handle.h` around lines 313 - 328, Add bounds
validation to BufferRefBlobView::ref before computing the byte offset or calling
memcpy, rejecting indices below zero or greater than or equal to ref_count with
the established assertion or exception mechanism. Preserve the existing
BufferRef validation and extraction behavior for valid indices.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/buffer-handle-abi.md`:
- Around line 174-186: Add a VMM_WINDOW row to the Backends table, documenting
that it materializes as the device VA carved by allocate_domain and is used for
communication-domain window buffers. Keep it alongside DEVICE_MALLOC and
preserve the table’s wire-ABI completeness statement.

In `@python/simpler/buffer_handle.py`:
- Around line 239-242: Update the layout comment immediately above
_BUFFER_REF_TAIL to use the actual wire sizes: BufferRef 144 B and
BufferHandleDescriptor 88 B, while preserving the existing field description and
size assertion.

In `@src/common/task_interface/buffer_handle.h`:
- Around line 80-96: Update validate_buffer_ref to reject any BufferRef whose
backend_kind is FORK_COW unless access is exactly READ, preserving the existing
address_space/backend_kind validation for all other combinations. Add or extend
C++ validation tests to cover FORK_COW with WRITE and READWRITE access as
rejected, while retaining acceptance for FORK_COW with READ.

---

Nitpick comments:
In `@src/common/task_interface/buffer_handle.h`:
- Around line 313-328: Add bounds validation to BufferRefBlobView::ref before
computing the byte offset or calling memcpy, rejecting indices below zero or
greater than or equal to ref_count with the established assertion or exception
mechanism. Preserve the existing BufferRef validation and extraction behavior
for valid indices.

In `@tests/ut/cpp/types/test_buffer_handle.cpp`:
- Around line 71-82: Add an assertion in BufferHandleAbi.EnumValuesAreFrozen
that verifies BackendKind::FORK_COW converts to uint8_t value 5, preserving the
existing checks for BackendKind values 0–4.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d442b3d1-f5cd-43eb-b613-298f4efd8dd7

📥 Commits

Reviewing files that changed from the base of the PR and between 6bd6c3b and cb27557.

📒 Files selected for processing (12)

• docs/README.md
• docs/buffer-handle-abi.md
• mkdocs.yml
• python/bindings/task_interface.cpp
• python/simpler/buffer_handle.py
• python/simpler/worker.py
• src/common/task_interface/buffer_handle.h
• src/common/task_interface/data_type.h
• src/common/task_interface/tensor.h
• tests/ut/cpp/CMakeLists.txt
• tests/ut/cpp/types/test_buffer_handle.cpp
• tests/ut/py/test_buffer_handle.py

💤 Files with no reviewable changes (1)

• src/common/task_interface/tensor.h

[YunjiQin]

Went through the CodeRabbit findings — all five held up against the current code, none was a false positive. Fixed in 9fe7bb9.

The one that mattered: validate_buffer_ref is documented as the single gate every receive boundary runs, but the FORK_COW⇒READ rule only existed in the Python mirror's descriptor constructor. A FORK_COW descriptor arriving over the wire with a write grant passed C++ decode — and the failure is silent, not loud: the consumer's first write splits the page into a private copy and the owner observes nothing. Both mirrors reject it now, with a test covering WRITE and READWRITE plus the FORK_SHM case that stays legal.

• BufferRefBlobView::ref(i) bounds check — agreed and added. Not reachable today (every caller loops to ref_count), but it is the documented extraction point for three consumers and nothing tells a fourth that the bound is the caller's job.
• FORK_COW = 5 not pinned — correct, it was the one enumerator the frozen-value test skipped.
• Stale BufferRef layout comment — correct: it still said 272 B / 216 B from before the ABI was slimmed. Actual is 144 / 88, which the assertion on the next line already enforced.
• VMM_WINDOW missing from the backend table — correct, the table listed five of the six wire values.

On the docstring-coverage warning (32% vs 80%): added docstrings where they state a contract that is not evident from the signature — the two wire enums, BufferHandle.to_descriptor / close, and ImportRegistry.resolve / unregister / close (notably: close on the owner unlinks, close on the registry does not, which is the kind of thing worth writing down). I deliberately did not document the mechanical dunders (__len__, __post_init__, __getitem__) to reach the threshold — the repo's own gate has no docstring check, and one-line restatements of what the signature already says are what the project's comment rule steers away from.

Verified after the fixes: pyut 913 passed, cpput 67/67, a2a3sim scene tests 43 passed.

[ChaoWao]

Naming direction from the repository-wide audit is now captured in #1676. The relevant rule is: software identifiers use the owning entity (Worker / Chip / Core), while numeric levels remain architecture prose only.

For this PR, the canonical model should be:

Worker domain:  Tensor      — address-free, cross-edge logical view
Chip domain:    ChipTensor  — materialized GM-address-bearing TMR/HBG tensor

The current head does not yet satisfy that model:

1. C++ global ::Tensor is the Chip-owned TMR/HBG POD, but only its Python binding is renamed to ChipTensor. The C++ type should also become ChipTensor (a temporary using Tensor = ChipTensor compatibility alias is fine for external kernel sources). Do not introduce L2Tensor or LocalTensor.
2. Python simpler.buffer.Tensor is a separate dataclass mirror of C++ simpler::Tensor. Public Python and C++ Tensor must be the same canonical type and semantics; prefer binding simpler::Tensor directly rather than maintaining a second public implementation.
3. simpler.task_interface.Tensor is documented as the object users submit, but TaskArgs.add_tensor currently rejects it and accepts only ChipTensor | RemoteTensorRef. Either complete the TaskArgs<Tensor> wire cutover here, or keep the new type explicitly internal/foundation-only until that cutover. Do not expose a public Tensor whose advertised operation rejects it.
4. The intended later argument naming is TaskArgs<Tensor> at the Worker layer and ChipTaskArgs<ChipTensor> at the Chip boundary (the current ChipStorageTaskArgs). Existing L0TaskArgs / L2TaskArgs naming can migrate separately to CoreTaskArgs / Chip-owned names; it need not expand this PR.

The important merge condition for #1599 is not a repository-wide rename. It is that the new ABI does not establish a second public meaning for Tensor, or a Python/C++ name mismatch that every later cutover must preserve.