fixup! buffer: support aligned allocations

Address Copilot review feedback:

- The test asserted `buf.byteOffset % alignment === 0`, which does not
  hold: the padding an allocation needs depends on where its backing
  store lands, so an aligned buffer's `byteOffset` is congruent to
  `-address` modulo `alignment`, not to 0. Check alignment against
  `arrayBufferAlignedOffset()` instead, which makes the address
  alignment genuinely observable from JS rather than only asserted by
  the binding's CHECKs.
- Correct the pre-existing `@returns {FastBuffer|undefined}` on
  `Buffer.allocUnsafeSlow()`; it never returns undefined.

Assisted-by: Claude/Opus 5
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ronag

lib/buffer.js

@@ -487,7 +487,7 @@ Buffer.allocUnsafe = function allocUnsafe(size, alignment) {
  * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
  * @param {number} [alignment] A power of two, at most 2 ** 30
- * @returns {FastBuffer|undefined}
+ * @returns {FastBuffer}
  */
 Buffer.allocUnsafeSlow = function allocUnsafeSlow(size, alignment) {
   validateNumber(size, 'size', 0, kMaxLength);

test/parallel/test-buffer-alloc-alignment.js

@@ -1,13 +1,28 @@
+// Flags: --expose-internals
 'use strict';
 require('../common');
 const assert = require('assert');
 const { Buffer, constants } = require('buffer');
+const { internalBinding } = require('internal/test/binding');
+const { arrayBufferAlignedOffset } = internalBinding('buffer');
 
 // Buffer.allocUnsafe(size, alignment) and Buffer.allocUnsafeSlow(size,
 // alignment) return a buffer whose memory starts at an address that is a
-// multiple of `alignment`. The address is not observable from JS, but the
-// binding asserts it internally, so exercising a range of sizes and alignments
-// here is what validates it.
+// multiple of `alignment`.
+
+// Addresses are not observable from JS, so alignment cannot be checked against
+// `byteOffset` alone: the padding an allocation needs depends on where its
+// backing store happens to land. `arrayBufferAlignedOffset(ab, alignment)`
+// returns an offset into `ab` that is known to be aligned, so any other offset
+// is aligned exactly when it is congruent to that one.
+function assertAligned(buf, alignment) {
+  const aligned = arrayBufferAlignedOffset(buf.buffer, alignment);
+  // `aligned` is in [0, alignment), so adding `alignment` keeps this positive.
+  const skew = (buf.byteOffset - aligned + alignment) % alignment;
+  assert.strictEqual(skew, 0,
+                     `byteOffset ${buf.byteOffset} is not ${alignment} byte ` +
+                     `aligned (aligned offsets are ${aligned} mod ${alignment})`);
+}
 
 const alignments = [1, 2, 4, 8, 16, 64, 512, 4096, 65536];
 const sizes = [0, 1, 7, 64, 65, 512, 4096, 100000];
@@ -17,7 +32,9 @@ for (const alloc of [Buffer.allocUnsafe, Buffer.allocUnsafeSlow]) {
     for (const size of sizes) {
       const buf = alloc(size, alignment);
       assert.strictEqual(buf.length, size);
-      // Backing store address alignment is not observable from JS; the internal binding CHECKs it.
+      if (size > 0) {
+        assertAligned(buf, alignment);
+      }
       // The view must fit inside the (over-allocated) ArrayBuffer.
       assert.ok(buf.byteOffset + size <= buf.buffer.byteLength);
       // The whole buffer must be writable through the aligned view.
@@ -111,6 +128,9 @@ for (const alloc of [Buffer.allocUnsafe, Buffer.allocUnsafeSlow]) {
   // Pooled, so consecutive allocations share an ArrayBuffer. A pool may be
   // exhausted in between, hence checking that any two neighbours share one.
   assert.ok(bufs.some((buf, i) => i > 0 && buf.buffer === bufs[i - 1].buffer));
+  for (const buf of bufs) {
+    assertAligned(buf, 64);
+  }
 
   // Stricter than the pool alignment, so this gets its own ArrayBuffer.
   const own = Buffer.allocUnsafe(64, 128);
@@ -126,7 +146,7 @@ for (const alloc of [Buffer.allocUnsafe, Buffer.allocUnsafeSlow]) {
       Buffer.allocUnsafe(24) :
       Buffer.allocUnsafe(24, 16);
     if (i % 2 === 1) {
-      assert.strictEqual(buf.byteOffset % 16, 0);
+      assertAligned(buf, 16);
     }
     buf.fill(i % 256);
     bufs.push(buf);