knitting 0.1.51 → 0.1.52

package/src/connections/shared-array-buffer-payload.js

@@ -0,0 +1,235 @@
+import { RUNTIME } from "../common/runtime.js";
+import { getNodeProcess } from "../common/node-compat.js";
+import { getBufferReferenceCapabilities } from "./buffer-reference-native.js";
+// Thread-worker SharedArrayBuffer transport by process-local pointer.
+// SABs are shared, not moved or detached; process workers reject them.
+export const SHARED_ARRAY_BUFFER_CODEC_ID = "knitting.sharedArrayBuffer";
+export const SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER = Symbol.for("knitting.sharedArrayBuffer.numericTransfer");
+export const SHARED_ARRAY_BUFFER_NUMERIC_WORDS = 8;
+const SHARED_ARRAY_BUFFER_TOKEN_NUMERIC_WORDS = 2;
+const EXTERNAL_PAYLOAD_BRAND = Symbol.for("knitting.payloadCodec");
+const getProcessId = () => {
+    const proc = getNodeProcess();
+    if (proc !== undefined && typeof proc.pid === "number")
+        return proc.pid;
+    const deno = globalThis.Deno;
+    if (typeof deno?.pid === "number")
+        return deno.pid;
+    return 0;
+};
+const PROCESS_ORIGIN = `${RUNTIME}:${getProcessId()}`;
+const hasSharedArrayBuffer = typeof SharedArrayBuffer === "function";
+export const isSharedArrayBufferValue = (value) => hasSharedArrayBuffer && value instanceof SharedArrayBuffer;
+const pinnedBySab = new WeakMap();
+const payloadBySharedBuffer = new WeakMap();
+const warmedTokensByTransport = new WeakMap();
+const cachedSharedBuffersByToken = new Map();
+const pinFinalizer = typeof FinalizationRegistry === "function"
+    ? new FinalizationRegistry((token) => {
+        try {
+            getBufferReferenceCapabilities().releaseShared(token);
+        }
+        catch {
+            // best effort
+        }
+    })
+    : undefined;
+const splitU64 = (value) => [
+    Number(value & 0xffffffffn) >>> 0,
+    Number((value >> 32n) & 0xffffffffn) >>> 0,
+];
+const joinU64 = (low, high) => (BigInt(high >>> 0) << 32n) | BigInt(low >>> 0);
+const encodeRuntime = (runtime) => {
+    switch (runtime) {
+        case "node":
+            return 1;
+        case "deno":
+            return 2;
+        case "bun":
+            return 3;
+        default:
+            return 0;
+    }
+};
+const decodeRuntime = (value) => {
+    switch (value) {
+        case 1:
+            return "node";
+        case 2:
+            return "deno";
+        case 3:
+            return "bun";
+        default:
+            return undefined;
+    }
+};
+const getWarmTokens = (transportKey) => {
+    if (transportKey === undefined)
+        return undefined;
+    let warmTokens = warmedTokensByTransport.get(transportKey);
+    if (warmTokens === undefined) {
+        warmTokens = new Set();
+        warmedTokensByTransport.set(transportKey, warmTokens);
+    }
+    return warmTokens;
+};
+const pinSab = (sab) => {
+    let pin = pinnedBySab.get(sab);
+    if (pin === undefined) {
+        const produced = getBufferReferenceCapabilities().produceShared(sab);
+        pin = {
+            token: produced.token,
+            pointer: produced.pointer,
+            byteLength: produced.byteLength,
+        };
+        pinnedBySab.set(sab, pin);
+        pinFinalizer?.register(sab, pin.token);
+    }
+    return pin;
+};
+const makeMetadata = (pin) => ({
+    kind: SHARED_ARRAY_BUFFER_CODEC_ID,
+    origin: PROCESS_ORIGIN,
+    runtime: RUNTIME,
+    pointer: pin.pointer.toString(),
+    token: pin.token.toString(),
+    byteLength: pin.byteLength,
+});
+const makeFullNumericMetadata = (pin) => {
+    if (pin.byteLength > 0xffffffff)
+        return undefined;
+    const [tokenLow, tokenHigh] = splitU64(pin.token);
+    const [pointerLow, pointerHigh] = splitU64(pin.pointer);
+    return [
+        tokenLow,
+        tokenHigh,
+        pointerLow,
+        pointerHigh,
+        pin.byteLength >>> 0,
+        encodeRuntime(RUNTIME),
+        getProcessId() >>> 0,
+        0,
+    ];
+};
+const makeTokenNumericMetadata = (pin) => {
+    const [tokenLow, tokenHigh] = splitU64(pin.token);
+    return [tokenLow, tokenHigh];
+};
+/** Wrap a SAB as external payload; GC-managed pins mean no settle finalizer. */
+export const wrapSharedArrayBufferPayload = (sab) => {
+    let payload = payloadBySharedBuffer.get(sab);
+    if (payload !== undefined)
+        return payload;
+    const pin = pinSab(sab);
+    payload = createSharedArrayBufferPayload(sab, pin, makeMetadata(pin));
+    return payload;
+};
+const createSharedArrayBufferPayload = (buffer, pin, metadata) => {
+    let payload = payloadBySharedBuffer.get(buffer);
+    if (payload !== undefined)
+        return payload;
+    const fullNumeric = makeFullNumericMetadata(pin);
+    const tokenOnlyNumeric = makeTokenNumericMetadata(pin);
+    payload = {
+        [EXTERNAL_PAYLOAD_BRAND]: SHARED_ARRAY_BUFFER_CODEC_ID,
+        toMetadata: () => metadata,
+        [SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER]: (transportKey) => {
+            if (fullNumeric === undefined) {
+                return undefined;
+            }
+            const warmTokens = getWarmTokens(transportKey);
+            if (warmTokens === undefined)
+                return fullNumeric;
+            if (warmTokens.has(pin.token))
+                return tokenOnlyNumeric;
+            warmTokens.add(pin.token);
+            return fullNumeric;
+        },
+    };
+    payloadBySharedBuffer.set(buffer, payload);
+    return payload;
+};
+export const getSharedArrayBufferPayload = (value) => {
+    if (isSharedArrayBufferValue(value))
+        return wrapSharedArrayBufferPayload(value);
+    return payloadBySharedBuffer.get(value);
+};
+const isSharedArrayBufferMetadata = (value) => {
+    if (value === null || typeof value !== "object")
+        return false;
+    const meta = value;
+    return (meta.kind === SHARED_ARRAY_BUFFER_CODEC_ID &&
+        typeof meta.origin === "string" &&
+        typeof meta.runtime === "string" &&
+        typeof meta.pointer === "string" &&
+        typeof meta.token === "string" &&
+        typeof meta.byteLength === "number" &&
+        Number.isInteger(meta.byteLength) &&
+        meta.byteLength >= 0);
+};
+const materializeSharedBuffer = (metadata, warmOnly) => {
+    if (metadata.origin !== PROCESS_ORIGIN) {
+        throw new Error(`SharedArrayBuffer cannot cross a process boundary (origin ${metadata.origin} ` +
+            `!= ${PROCESS_ORIGIN}); it is shared by reference to thread workers only.`);
+    }
+    const token = BigInt(metadata.token);
+    const cached = cachedSharedBuffersByToken.get(token);
+    if (cached !== undefined)
+        return cached;
+    if (warmOnly) {
+        throw new TypeError("SharedArrayBuffer cache miss for warm token payload");
+    }
+    const region = getBufferReferenceCapabilities().adoptShared({
+        token,
+        pointer: BigInt(metadata.pointer),
+        byteOffset: 0,
+        byteLength: metadata.byteLength,
+    });
+    cachedSharedBuffersByToken.set(token, region.buffer);
+    createSharedArrayBufferPayload(region.buffer, {
+        token,
+        pointer: BigInt(metadata.pointer),
+        byteLength: metadata.byteLength,
+    }, metadata);
+    return region.buffer;
+};
+const decode = (metadata) => {
+    if (!isSharedArrayBufferMetadata(metadata)) {
+        throw new TypeError("Invalid SharedArrayBuffer payload metadata");
+    }
+    return materializeSharedBuffer(metadata, false);
+};
+const decodeNumeric = (words) => {
+    if (words.length === SHARED_ARRAY_BUFFER_TOKEN_NUMERIC_WORDS) {
+        const token = joinU64(words[0] ?? 0, words[1] ?? 0);
+        const cached = cachedSharedBuffersByToken.get(token);
+        if (cached !== undefined)
+            return cached;
+        throw new TypeError("SharedArrayBuffer cache miss for warm token payload");
+    }
+    const runtime = decodeRuntime(words[5] ?? 0);
+    if (runtime === undefined) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric runtime");
+    }
+    const originPid = words[6];
+    if (originPid === undefined ||
+        !Number.isInteger(originPid) ||
+        originPid < 0) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric origin");
+    }
+    if (words.length !== SHARED_ARRAY_BUFFER_NUMERIC_WORDS) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric word count");
+    }
+    const metadata = {
+        kind: SHARED_ARRAY_BUFFER_CODEC_ID,
+        origin: `${runtime}:${originPid >>> 0}`,
+        runtime,
+        pointer: joinU64(words[2] ?? 0, words[3] ?? 0).toString(),
+        token: joinU64(words[0] ?? 0, words[1] ?? 0).toString(),
+        byteLength: words[4] ?? 0,
+    };
+    return materializeSharedBuffer(metadata, false);
+};
+const codecGlobal = globalThis;
+const codecs = codecGlobal.__KNITTING_PAYLOAD_CODECS__ ??= Object.create(null);
+codecs[SHARED_ARRAY_BUFFER_CODEC_ID] = { decode, decodeNumeric };

package/src/knitting_buffer_pointer.cc

@@ -0,0 +1,425 @@
+#if !defined(__linux__) && !defined(__APPLE__) && !defined(_WIN32)
+#error "knitting_buffer_pointer.cc currently supports Linux, macOS, and Windows."
+#endif
+
+#include <node.h>
+#include <v8.h>
+
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+
+namespace knitting_buffer_pointer {
+
+struct RetainedReference {
+  v8::Isolate* isolate;
+  v8::Global<v8::Value> value;
+};
+
+std::mutex retained_mutex;
+uint64_t next_retained_id = 1;
+std::unordered_map<uint64_t, std::unique_ptr<RetainedReference>> retained_refs;
+
+// BackingStore is isolate-independent, unlike v8::Global<Value>.
+// Consumers can co-own moved bytes while the registry keeps producer liveness.
+struct RetainedBackingStore {
+  std::shared_ptr<v8::BackingStore> store;
+  size_t byte_offset;
+  size_t byte_length;
+};
+
+std::mutex backing_mutex;
+uint64_t next_backing_id = 1;
+std::unordered_map<uint64_t, RetainedBackingStore> retained_backings;
+
+void ThrowType(v8::Isolate* isolate, const char* message) {
+  isolate->ThrowException(v8::Exception::TypeError(
+    v8::String::NewFromUtf8(isolate, message).ToLocalChecked()
+  ));
+}
+
+v8::Local<v8::String> DetachKey(v8::Isolate* isolate) {
+  return v8::String::NewFromUtf8Literal(
+    isolate,
+    "knitting.bufferReference.detachKey"
+  );
+}
+
+bool DetachWithKey(
+  v8::Local<v8::ArrayBuffer> buffer,
+  v8::Local<v8::Value> key
+) {
+  v8::Maybe<bool> detached = buffer->Detach(key);
+  return (detached.IsJust() && detached.FromJust()) || buffer->WasDetached();
+}
+
+bool DetachDefaultArrayBuffer(v8::Local<v8::ArrayBuffer> buffer) {
+  if (buffer->WasDetached()) return true;
+  if (!buffer->IsDetachable()) return false;
+  return DetachWithKey(buffer, v8::Local<v8::Value>());
+}
+
+bool DetachKnittingArrayBuffer(
+  v8::Isolate* isolate,
+  v8::Local<v8::ArrayBuffer> buffer
+) {
+  if (buffer->WasDetached()) return true;
+  if (!buffer->IsDetachable()) return false;
+  if (DetachWithKey(buffer, DetachKey(isolate))) return true;
+  return DetachWithKey(buffer, v8::Local<v8::Value>());
+}
+
+bool ReadPointerInfo(
+  v8::Isolate* isolate,
+  v8::Local<v8::Value> value,
+  void** data,
+  size_t* byte_length
+) {
+  size_t byte_offset = 0;
+
+  if (value->IsArrayBufferView()) {
+    v8::Local<v8::ArrayBufferView> view = value.As<v8::ArrayBufferView>();
+    *data = view->Buffer()->Data();
+    byte_offset = view->ByteOffset();
+    *byte_length = view->ByteLength();
+  } else if (value->IsArrayBuffer()) {
+    v8::Local<v8::ArrayBuffer> buffer = value.As<v8::ArrayBuffer>();
+    *data = buffer->Data();
+    *byte_length = buffer->ByteLength();
+  } else if (value->IsSharedArrayBuffer()) {
+    v8::Local<v8::SharedArrayBuffer> buffer = value.As<v8::SharedArrayBuffer>();
+    *data = buffer->Data();
+    *byte_length = buffer->ByteLength();
+  } else {
+    ThrowType(
+      isolate,
+      "getPointer expects an ArrayBuffer, SharedArrayBuffer, or typed array"
+    );
+    return false;
+  }
+
+  *data = static_cast<uint8_t*>(*data) + byte_offset;
+  return true;
+}
+
+uint64_t ReadToken(
+  const v8::FunctionCallbackInfo<v8::Value>& args,
+  int index,
+  const char* message
+) {
+  v8::Isolate* isolate = args.GetIsolate();
+  if (args.Length() <= index || !args[index]->IsBigInt()) {
+    ThrowType(isolate, message);
+    return 0;
+  }
+
+  bool lossless = false;
+  uint64_t token = args[index].As<v8::BigInt>()->Uint64Value(&lossless);
+  if (token == 0) {
+    ThrowType(isolate, "retained pointer token must be non-zero");
+    return 0;
+  }
+  return token;
+}
+
+void GetPointer(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+
+  if (args.Length() < 1) {
+    ThrowType(isolate, "getPointer(buffer) requires an ArrayBuffer or view");
+    return;
+  }
+
+  void* data = nullptr;
+  size_t byte_length = 0;
+  if (!ReadPointerInfo(isolate, args[0], &data, &byte_length)) return;
+
+  uintptr_t address = reinterpret_cast<uintptr_t>(data);
+  args.GetReturnValue().Set(
+    v8::BigInt::NewFromUnsigned(isolate, static_cast<uint64_t>(address))
+  );
+}
+
+void RetainPointer(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+  v8::Local<v8::Context> context = isolate->GetCurrentContext();
+
+  if (args.Length() < 1) {
+    ThrowType(isolate, "retainPointer(buffer) requires an ArrayBuffer or view");
+    return;
+  }
+
+  void* data = nullptr;
+  size_t byte_length = 0;
+  if (!ReadPointerInfo(isolate, args[0], &data, &byte_length)) return;
+
+  auto retained = std::make_unique<RetainedReference>();
+  retained->isolate = isolate;
+  retained->value.Reset(isolate, args[0]);
+
+  uint64_t token = 0;
+  {
+    std::lock_guard<std::mutex> lock(retained_mutex);
+    token = next_retained_id++;
+    if (token == 0) token = next_retained_id++;
+    retained_refs.emplace(token, std::move(retained));
+  }
+
+  v8::Local<v8::Object> result = v8::Object::New(isolate);
+  result->Set(
+    context,
+    v8::String::NewFromUtf8Literal(isolate, "pointer"),
+    v8::BigInt::NewFromUnsigned(
+      isolate,
+      static_cast<uint64_t>(reinterpret_cast<uintptr_t>(data))
+    )
+  ).ToChecked();
+  result->Set(
+    context,
+    v8::String::NewFromUtf8Literal(isolate, "byteLength"),
+    v8::Number::New(isolate, static_cast<double>(byte_length))
+  ).ToChecked();
+  result->Set(
+    context,
+    v8::String::NewFromUtf8Literal(isolate, "token"),
+    v8::BigInt::NewFromUnsigned(isolate, token)
+  ).ToChecked();
+  args.GetReturnValue().Set(result);
+}
+
+void ReleasePointer(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  uint64_t token = ReadToken(args, 0, "releasePointer(token) requires a bigint");
+  if (token == 0) return;
+
+  std::unique_ptr<RetainedReference> retained;
+  {
+    std::lock_guard<std::mutex> lock(retained_mutex);
+    auto found = retained_refs.find(token);
+    if (found == retained_refs.end()) {
+      args.GetReturnValue().Set(false);
+      return;
+    }
+    retained = std::move(found->second);
+    retained_refs.erase(found);
+  }
+
+  retained->value.Reset();
+  args.GetReturnValue().Set(true);
+}
+
+void NoopDeleter(void*, size_t, void*) {}
+
+void WrapPointer(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+  v8::Local<v8::Context> context = isolate->GetCurrentContext();
+
+  if (args.Length() < 2 || !args[0]->IsBigInt() || !args[1]->IsNumber()) {
+    ThrowType(
+      isolate,
+      "wrapPointer(pointer: bigint, byteLength: number) requires both arguments"
+    );
+    return;
+  }
+
+  bool lossless = false;
+  uint64_t address = args[0].As<v8::BigInt>()->Uint64Value(&lossless);
+  if (address == 0) {
+    ThrowType(isolate, "wrapPointer received a null pointer");
+    return;
+  }
+
+  v8::Maybe<int64_t> maybe_length = args[1]->IntegerValue(context);
+  if (maybe_length.IsNothing() || maybe_length.FromJust() < 0) {
+    ThrowType(isolate, "byteLength must be a non-negative integer");
+    return;
+  }
+  size_t byte_length = static_cast<size_t>(maybe_length.FromJust());
+
+  void* data = reinterpret_cast<void*>(static_cast<uintptr_t>(address));
+  std::unique_ptr<v8::BackingStore> backing = v8::ArrayBuffer::NewBackingStore(
+    data,
+    byte_length,
+    NoopDeleter,
+    nullptr
+  );
+  std::shared_ptr<v8::BackingStore> shared(std::move(backing));
+  v8::Local<v8::ArrayBuffer> buffer = v8::ArrayBuffer::New(isolate, shared);
+  buffer->SetDetachKey(DetachKey(isolate));
+  args.GetReturnValue().Set(buffer);
+}
+
+void DetachArrayBuffer(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+
+  if (args.Length() < 1 || !args[0]->IsArrayBuffer()) {
+    ThrowType(isolate, "detachArrayBuffer(buffer) requires an ArrayBuffer");
+    return;
+  }
+
+  v8::Local<v8::ArrayBuffer> buffer = args[0].As<v8::ArrayBuffer>();
+  if (buffer->WasDetached()) {
+    args.GetReturnValue().Set(true);
+    return;
+  }
+  args.GetReturnValue().Set(DetachKnittingArrayBuffer(isolate, buffer));
+}
+
+// Read the underlying ArrayBuffer + region of an ArrayBuffer or typed-array view.
+// SharedArrayBuffer is rejected: it is already shareable and must not be detached.
+bool ReadArrayBufferRegion(
+  v8::Isolate* isolate,
+  v8::Local<v8::Value> value,
+  v8::Local<v8::ArrayBuffer>* buffer,
+  size_t* byte_offset,
+  size_t* byte_length
+) {
+  if (value->IsArrayBufferView()) {
+    v8::Local<v8::ArrayBufferView> view = value.As<v8::ArrayBufferView>();
+    *buffer = view->Buffer();
+    *byte_offset = view->ByteOffset();
+    *byte_length = view->ByteLength();
+    return true;
+  }
+  if (value->IsArrayBuffer()) {
+    v8::Local<v8::ArrayBuffer> ab = value.As<v8::ArrayBuffer>();
+    *buffer = ab;
+    *byte_offset = 0;
+    *byte_length = ab->ByteLength();
+    return true;
+  }
+  ThrowType(
+    isolate,
+    "retainBackingStore expects an ArrayBuffer or typed array (not a SharedArrayBuffer)"
+  );
+  return false;
+}
+
+// retainBackingStore(buffer) -> { pointer, byteOffset, byteLength, token }
+// Registry-pins the backing store, then detaches the source for the move.
+void RetainBackingStore(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+  v8::Local<v8::Context> context = isolate->GetCurrentContext();
+
+  if (args.Length() < 1) {
+    ThrowType(isolate, "retainBackingStore(buffer) requires an ArrayBuffer or view");
+    return;
+  }
+
+  v8::Local<v8::ArrayBuffer> buffer;
+  size_t byte_offset = 0;
+  size_t byte_length = 0;
+  if (!ReadArrayBufferRegion(isolate, args[0], &buffer, &byte_offset, &byte_length)) {
+    return;
+  }
+
+  std::shared_ptr<v8::BackingStore> store = buffer->GetBackingStore();
+  uint8_t* base = static_cast<uint8_t*>(store->Data());
+  uintptr_t address = reinterpret_cast<uintptr_t>(base + byte_offset);
+
+  // Detach only after taking the shared_ptr; ordinary JS buffers use no key.
+  DetachDefaultArrayBuffer(buffer);
+
+  uint64_t token = 0;
+  {
+    std::lock_guard<std::mutex> lock(backing_mutex);
+    token = next_backing_id++;
+    if (token == 0) token = next_backing_id++;
+    retained_backings.emplace(
+      token,
+      RetainedBackingStore{ std::move(store), byte_offset, byte_length }
+    );
+  }
+
+  v8::Local<v8::Object> result = v8::Object::New(isolate);
+  result->Set(
+    context,
+    v8::String::NewFromUtf8Literal(isolate, "pointer"),
+    v8::BigInt::NewFromUnsigned(isolate, static_cast<uint64_t>(address))
+  ).ToChecked();
+  result->Set(
+    context,
+    v8::String::NewFromUtf8Literal(isolate, "byteOffset"),
+    v8::Number::New(isolate, static_cast<double>(byte_offset))
+  ).ToChecked();
+  result->Set(
+    context,
+    v8::String::NewFromUtf8Literal(isolate, "byteLength"),
+    v8::Number::New(isolate, static_cast<double>(byte_length))
+  ).ToChecked();
+  result->Set(
+    context,
+    v8::String::NewFromUtf8Literal(isolate, "token"),
+    v8::BigInt::NewFromUnsigned(isolate, token)
+  ).ToChecked();
+  args.GetReturnValue().Set(result);
+}
+
+// adoptBackingStore(token) -> ArrayBuffer
+// Returns an ArrayBuffer in the caller's isolate that co-owns the registry store.
+// The registry entry remains until producer release.
+void AdoptBackingStore(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+  uint64_t token = ReadToken(args, 0, "adoptBackingStore(token) requires a bigint");
+  if (token == 0) return;
+
+  std::shared_ptr<v8::BackingStore> store;
+  {
+    std::lock_guard<std::mutex> lock(backing_mutex);
+    auto found = retained_backings.find(token);
+    if (found == retained_backings.end()) {
+      ThrowType(isolate, "adoptBackingStore: unknown or released token");
+      return;
+    }
+    store = found->second.store;
+  }
+
+  v8::Local<v8::ArrayBuffer> buffer = v8::ArrayBuffer::New(isolate, store);
+  buffer->SetDetachKey(DetachKey(isolate));
+  args.GetReturnValue().Set(buffer);
+}
+
+// releaseBackingStore(token) -> boolean
+// Drops the registry's reference. The store is freed only if no consumer adopted.
+void ReleaseBackingStore(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  uint64_t token =
+    ReadToken(args, 0, "releaseBackingStore(token) requires a bigint");
+  if (token == 0) return;
+
+  RetainedBackingStore released;
+  bool found = false;
+  {
+    std::lock_guard<std::mutex> lock(backing_mutex);
+    auto it = retained_backings.find(token);
+    if (it != retained_backings.end()) {
+      released = std::move(it->second);
+      retained_backings.erase(it);
+      found = true;
+    }
+  }
+  // released.store drops here, outside the lock.
+  args.GetReturnValue().Set(found);
+}
+
+// SAB transport avoids SharedArrayBuffer::New across isolates: worker teardown
+// can corrupt the shared store. JS pins plus non-owning aliases keep native
+// handles from outliving their isolate.
+
+void Initialize(
+  v8::Local<v8::Object> exports,
+  v8::Local<v8::Value>,
+  v8::Local<v8::Context>
+) {
+  NODE_SET_METHOD(exports, "getPointer", GetPointer);
+  NODE_SET_METHOD(exports, "retainPointer", RetainPointer);
+  NODE_SET_METHOD(exports, "releasePointer", ReleasePointer);
+  NODE_SET_METHOD(exports, "wrapPointer", WrapPointer);
+  NODE_SET_METHOD(exports, "detachArrayBuffer", DetachArrayBuffer);
+  NODE_SET_METHOD(exports, "retainBackingStore", RetainBackingStore);
+  NODE_SET_METHOD(exports, "adoptBackingStore", AdoptBackingStore);
+  NODE_SET_METHOD(exports, "releaseBackingStore", ReleaseBackingStore);
+}
+
+NODE_MODULE_CONTEXT_AWARE(NODE_GYP_MODULE_NAME, Initialize)
+
+}

package/src/memory/lock.d.ts

@@ -49,7 +49,13 @@ export declare enum PayloadBuffer {
     EnvelopeDynamicHeaderString = 43,
     ExternalPayload = 44,
     StaticExternalPayload = 45,
-    ProcessSharedBuffer = 46
+    ProcessSharedBuffer = 46,
+    BufferReference = 47,
+    SharedArrayBuffer = 48,
+    EnvelopeStaticHeaderExternal = 49,
+    EnvelopeDynamicHeaderExternal = 50,
+    EnvelopeStaticHeaderStringExternal = 51,
+    EnvelopeDynamicHeaderStringExternal = 52
 }
 export declare enum LockBound {
     paddingLock = 0,
@@ -70,15 +76,20 @@ export type Task = [
     number
 ] & {
     value: unknown;
+    finalize?: (() => void) | undefined;
     resolve: (value?: unknown) => void;
     reject: (reason?: unknown) => void;
 };
+export declare const PayloadTransportFinalizer: unique symbol;
 export declare const PromisePayloadMarker: unique symbol;
 export type PromisePayloadHandler = (task: Task, isRejected: boolean, value: unknown) => void;
 export declare const beginPromisePayload: (task: Task) => boolean;
 export declare const finishPromisePayload: (task: Task) => void;
 export declare const isPromisePayloadPending: (task: Task) => boolean;
 export declare const resetTaskLocalFlags: (task: Task) => void;
+export declare const addTaskFinalizer: (task: Task, finalizer: () => void) => void;
+export declare const attachPayloadTransportFinalizer: (task: Task, value: unknown) => void;
+export declare const runTaskFinalizers: (task: Task) => void;
 export declare enum TaskIndex {
     /**
      * Worker -> host response flags word.