Instruction file imported from bitstormFA/rew (.github/instructions/buffer-device.instructions.md). Copyright stays with the author.

Layer 2 — Buffer ownership, device, dtype, sharding

Name: buffer-device
Author: bitstormFA

The thin layer between the raw C API and everything above.

Hard rules

BufferHandle is the only ref object allowed in this layer (and one of only a few in the entire codebase). Its =destroy hook is the single point that calls into PJRT to release a buffer; it must be exception-safe and idempotent (donated/already-released handles are a no-op).
A BufferHandle carries a state field with at least Live and Donated. Any operation on a Donated handle must raise BufferDonatedError with a message pointing at the originating jit call.
Device is a value type ((target, ordinal)). The default-target resolution happens once per thread (cuda13 > cuda12 > rocm > cpu) and is overridable via REW_TARGET and setDefaultDevice.
Sharding carries replicated, partitioned, or manual annotations. Keep it metadata-first: validation is allowed, but sharding must not introduce implicit host or cross-device transfers.
DType is a closed enum; conversions to/from native Nim scalar types are exhaustive case matches.

Skills to follow

nim-ownership-hooks for =destroy/=copy/=sink semantics on BufferHandle.
nim-api-design for the public surface (initDevice, defaultDevice, etc.).
nim-error-handling for BufferDonatedError and other failure modes.

{ "ocm": "1", "id": "bitstormfa-rew-buffer-device-instructions", "kind": "skill", "name": "buffer-device", "description": "The thin layer between the raw C API and everything above.", "publisher": "bitstormFA", "version": "1.0.0", "capabilities": { "domains": [ "coding" ], "tags": [ "skill-md", "github-instructions" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "The thin layer between the raw C API and everything above." ], "primary": false, "metadata": { "source": { "provider": "github-instructions", "repository": "https://github.com/bitstormFA/rew", "path": ".github/instructions/buffer-device.instructions.md", "ref": "f6b4648ee26f228b4e62f0fdf689e0e93cf8b461", "url": "https://github.com/bitstormFA/rew/blob/f6b4648ee26f228b4e62f0fdf689e0e93cf8b461/.github/instructions/buffer-device.instructions.md", "key": "bitstormFA/rew/.github/instructions/buffer-device.instructions.md" }, "applies_to": "src/rew/{buffer,device,dtype,sharding}.nim" }, "instructions": "# Layer 2 — Buffer ownership, device, dtype, sharding\n\nThe thin layer between the raw C API and everything above.\n\n## Hard rules\n\n- `BufferHandle` is the **only** `ref object` allowed in this layer (and one\n of only a few in the entire codebase). Its `=destroy` hook is the single\n point that calls into PJRT to release a buffer; it must be exception-safe\n and idempotent (donated/already-released handles are a no-op).\n- A `BufferHandle` carries a state field with at least `Live` and `Donated`.\n Any operation on a `Donated` handle must raise `BufferDonatedError` with a\n message pointing at t", "cost": { "context_tokens": 385 } }

buffer-device

About

Layer 2 — Buffer ownership, device, dtype, sharding

Hard rules

Skills to follow

Use it

Manifest

Reviews