Add: VMM_SHAREABLE canonical Buffer substrate

[ccyywwen]

Summary

This change adds the canonical Buffer substrate that #2198 consumes.

It introduces BackendKind.VMM_SHAREABLE, a module-private 88-byte
fieldwise BufferDescriptor codec, and private _wrap_vmm_shareable().
It does not change Region, endpoint identity, delegated-region control,
or worker-chip materialization. Those land in #2198.

Ordinary CommDomain VMM_WINDOW identity is unchanged. Existing
BackendKind values 0–5 and the 88-byte BufferDescriptor layout are
unchanged.

Why This Exists

Shareable-handle VMM is not the same importer contract as owner-chip
VMM_WINDOW. Region needs a precise actual-backend tag and a single
canonical descriptor encoding so PAYLOAD and COUNTER can be real
Buffers instead of a second private export schema.

The codec and wrapper have to exist before Region can adopt them. This
PR is that substrate only: it can be reviewed and tested as Buffer ABI,
without mixing in the Region cutover.

What This Lands

• BackendKind.VMM_SHAREABLE = 6, DEVICE-only, with a fixed 24-byte
  body:

  device_id:i32 | reserved0:u32 | shareable_handle:u64 | mapping_bytes:u64

  The generic validator checks structure: nonzero handle, zero
  reserved/tail, and mapping_bytes >= nbytes. It does not query
  runtime granularity or mapped addresses.

• A module-private fieldwise 88-byte BufferDescriptor wire codec:

  • encoder writes zero-initialized storage, including structural padding
    and unused body tail
  • decoder is strict and reuses the canonical validator
  • this is not a public .pack() API and does not enter
    buffer.__all__

• Private _wrap_vmm_shareable():

  • uses the caller-supplied CanonicalIdentity; it does not mint a
    new one
  • does not take native VMM cleanup authority

Focused Buffer tests cover malformed VMM bodies, codec round-trip,
wrapper close/visibility, and the C++ ABI layout.

Breaking Change

None for Region or delegated-region wire. Those remain on the previous
export schema until #2198.

Callers that assume BackendKind has only values 0–5 must accept the
new enumerator. Descriptor size and existing backend encodings do not
change.

Non-Goals

This change intentionally does not add:

• Region Provider/Consumer adoption or typed attachments
• endpoint nonce / allocator startup
• delegated-region allocate reply v2
• HOST_CPU or DEVICE_AICORE Region Providers
• a public wrap_vmm_shareable() / wrap_existing_posix_shm()
• public ResourceBundle, generic ImportRegistry, Buffer escape, or
  retain/release
• changes to ordinary CommDomain VMM_WINDOW identity
• Buffer ABI design-doc rewrites; those stay gated on this change
  merging to main

Stacking

Merge this before #2198. #2198 is stacked on this head and must rebase
onto main after this merge SHA is available.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: e2c9ee85-d53c-4010-9567-3232c0934b27

📥 Commits

Reviewing files that changed from the base of the PR and between bb3e1cb and 099f970.

📒 Files selected for processing (5)

• python/bindings/task_interface.cpp
• python/simpler/buffer.py
• src/common/task_interface/buffer.h
• tests/ut/cpp/types/test_buffer.cpp
• tests/ut/py/test_buffer.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds the VMM_SHAREABLE buffer backend, validates its 24-byte descriptor body, provides private 88-byte wire codecs, and adds Python wrapping and test coverage.

Changes

VMM shareable buffer support

Layer / File(s)	Summary
Descriptor contract and validation src/common/task_interface/buffer.h, tests/ut/cpp/types/test_buffer.cpp, tests/ut/py/test_buffer.py	Defines backend value 6, its 24-byte body, device capability rules, field validation, and malformed-descriptor tests.
Private descriptor wire codec python/bindings/task_interface.cpp	Adds explicit little-endian encoding and decoding for 88-byte descriptors. Decoding requires the exact size and canonical validation.
Python wrapper and dispatch coverage python/simpler/buffer.py, tests/ut/py/test_buffer.py	Adds _wrap_vmm_shareable and tests identity, lifecycle, codec behavior, public API boundaries, adapter selection, and materialization rejection.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 099f9

The new backend contract, codec, wrapper, and validation paths have focused coverage with no confirmed merge-blocking issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 40 functions across 5 files.	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 main change: adding the VMM_SHAREABLE canonical Buffer substrate.
Description check	✅ Passed	The description directly explains the new backend, wire codec, wrapper, scope, tests, and non-goals.

• Fix all pre-merge checks with AI

---

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

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

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