@rebon/cli-win32-x64 1.2.0 → 1.4.0

package/payload/plugin-host/src/cli.mjs

@@ -1,147 +1,147 @@
-#!/usr/bin/env node
-import { pathToFileURL } from 'node:url';
-import { NdjsonDecoder, SerializedWriter } from './framing.mjs';
-import { PluginHost } from './host.mjs';
-import { loadPlugin } from './loader.mjs';
-import { currentOwner } from './ownership.mjs';
-import { ProtocolError } from './protocol.mjs';
-
-export function diagnostic(stream, code, message) {
-  const bounded = String(message).replace(/[\r\n]+/g, ' ').slice(0, 512);
-  stream.write(`${JSON.stringify({ level: 'error', code, message: bounded })}\n`);
-}
-export function installHostConsole(stream) {
-  const write = (level, values) => stream.write(`${JSON.stringify({ level, message: values.map(String).join(' ').slice(0, 512) })}\n`);
-  return Object.freeze({ log: (...v) => write('info', v), info: (...v) => write('info', v), warn: (...v) => write('warn', v), error: (...v) => write('error', v) });
-}
-
-// Frames are not handled one-at-a-time.
-//
-// A request handler may itself call rebon — that is the whole Node → rebon
-// direction — and the answer to that call arrives as a frame on this very
-// stream. Awaiting each dispatch before reading the next would mean the handler
-// waits for a frame the loop cannot read until the handler returns: a deadlock
-// that no amount of care inside a plugin can avoid. So dispatches are tracked
-// rather than awaited, and everything that needs them finished waits here.
-/// Loads the module that decides what a plugin package *is*.
-///
-/// The host itself knows one shape: a module exporting `activate`. Anything
-/// else — a Cordis plugin mounted into a shared composition realm, say — is a
-/// different answer to the same question, and the host has no business knowing
-/// which answers exist. So rebon names the module that does, and this loads it.
-///
-/// The module exports `createLoader({ next })` and returns `{ load, unload }`;
-/// `next` is the built-in loader, so an adapter that does not recognise a
-/// package hands it back rather than reimplementing it.
-export async function resolveLoader(specifier, error) {
-  if (!specifier) return {};
-  const url = specifier.startsWith('file:') ? specifier : pathToFileURL(specifier).href;
-  const module = await import(url);
-  if (typeof module.createLoader !== 'function') {
-    throw new ProtocolError('loader_invalid', `${specifier} exports no createLoader`);
-  }
-  const seams = await module.createLoader({ next: loadPlugin });
-  if (typeof seams?.load !== 'function') {
-    throw new ProtocolError('loader_invalid', `${specifier} produced no load function`);
-  }
-  return seams;
-}
-
-export async function runHost({ input, output, error, loader }) {
-  const decoder = new NdjsonDecoder();
-  const writer = new SerializedWriter(output);
-  const host = new PluginHost(writer, loader ?? {});
-  const running = new Set();
-  let fatal = null;
-  const track = (promise) => {
-    const tracked = promise.catch((cause) => { fatal ??= cause; }).finally(() => running.delete(tracked));
-    running.add(tracked);
-  };
-  // Draining rather than a single `Promise.all`: a dispatch that is still
-  // running can schedule another one, and the process must not exit under it.
-  const quiesce = async () => { while (running.size > 0) await Promise.all([...running]); };
-  try {
-    for await (const chunk of input) {
-      for (const frame of decoder.push(chunk)) {
-        if (fatal) throw fatal;
-        if (host.shuttingDown) throw new ProtocolError('frame_after_shutdown', 'frame received after shutdown');
-        track(host.accept(frame));
-      }
-      if (fatal) throw fatal;
-      if (host.shuttingDown) { await quiesce(); if (fatal) throw fatal; return 0; }
-    }
-    decoder.finish();
-    await quiesce();
-    if (fatal) throw fatal;
-    diagnostic(error, 'connection_lost', 'stdin reached EOF before successful shutdown');
-    return 3;
-  } catch (cause) {
-    // Terminals already owed still have to reach stdout: a caller waiting on
-    // one is not made whole by the host exiting with a diagnosis.
-    await quiesce();
-    const code = cause?.code ?? 'host_failure';
-    diagnostic(error, code, cause?.message ?? 'host failed');
-    return code === 'write_error' ? 4 : 2;
-  }
-}
-
-/// A rejection nobody handled, said out loud instead of swallowed, and
-/// attributed where the async chain reaches back to an entry.
-///
-/// Node does not stop this process for one, and before T20 nothing else looked
-/// either: a plugin could start an async task, have it fail, and leave no trace
-/// anywhere rebon reads. Three rounds of T19 were spent on exactly that.
-///
-/// T20 recorded these as unattributed, believing a failed promise cannot say
-/// who created it. It can: `plugin/load` runs inside a store that survives
-/// timers, microtasks and awaits, so this handler reads the owner straight out
-/// of it. What escapes the chain — through an `EventEmitter`, a native callback
-/// or a third-party library — is still `unattributed`, which is the truthful
-/// answer and is kept distinct from a wrong one.
-///
-/// It never exits. A stray rejection in one plugin must not take down a host
-/// other plugins are being served from; a load still in flight is failed by its
-/// own path instead, which is the caller's to run.
-export function installRejectionDiagnostic(stream) {
-  process.on('unhandledRejection', (reason) => {
-    const first = String(reason?.stack ?? reason ?? '').split('\n')[0];
-    const owner = currentOwner();
-    if (owner === undefined) {
-      diagnostic(stream, 'unhandled_rejection', `unattributed: ${first}`);
-      return;
-    }
-    // `loading` says which of the two this is. While a load is in flight the
-    // entry did not install correctly and nothing depends on it yet, so the
-    // load fails and the composition skips it with a reason. Afterwards the
-    // plugin stays ready: a load that already succeeded cannot be un-failed,
-    // and tearing down a plane other entries serve from would cost far more
-    // than the one bad promise.
-    if (owner.loading) {
-      owner.rejection = first;
-      diagnostic(stream, 'unhandled_rejection', `plugin=${owner.entry} during load: ${first}`);
-      return;
-    }
-    diagnostic(stream, 'unhandled_rejection', `plugin=${owner.entry}: ${first}`);
-  });
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1]).href) {
-  installRejectionDiagnostic(process.stderr);
-  const flag = process.argv.indexOf('--loader');
-  const specifier = flag >= 0 ? process.argv[flag + 1] : process.env.REBON_PLUGIN_LOADER;
-  let loader;
-  try {
-    loader = await resolveLoader(specifier, process.stderr);
-  } catch (cause) {
-    // A host that cannot build the loader rebon asked for must not fall back to
-    // the built-in one: it would load a different set of plugins than the one
-    // rebon believes it asked for, and say nothing.
-    diagnostic(process.stderr, cause?.code ?? 'loader_failure', cause?.message ?? 'loader failed');
-    process.exitCode = 2;
-  }
-  if (loader !== undefined) {
-    process.exitCode = await runHost({
-      input: process.stdin, output: process.stdout, error: process.stderr, loader,
-    });
-  }
-}
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import { NdjsonDecoder, SerializedWriter } from './framing.mjs';
+import { PluginHost } from './host.mjs';
+import { loadPlugin } from './loader.mjs';
+import { currentOwner } from './ownership.mjs';
+import { ProtocolError } from './protocol.mjs';
+
+export function diagnostic(stream, code, message) {
+  const bounded = String(message).replace(/[\r\n]+/g, ' ').slice(0, 512);
+  stream.write(`${JSON.stringify({ level: 'error', code, message: bounded })}\n`);
+}
+export function installHostConsole(stream) {
+  const write = (level, values) => stream.write(`${JSON.stringify({ level, message: values.map(String).join(' ').slice(0, 512) })}\n`);
+  return Object.freeze({ log: (...v) => write('info', v), info: (...v) => write('info', v), warn: (...v) => write('warn', v), error: (...v) => write('error', v) });
+}
+
+// Frames are not handled one-at-a-time.
+//
+// A request handler may itself call rebon — that is the whole Node → rebon
+// direction — and the answer to that call arrives as a frame on this very
+// stream. Awaiting each dispatch before reading the next would mean the handler
+// waits for a frame the loop cannot read until the handler returns: a deadlock
+// that no amount of care inside a plugin can avoid. So dispatches are tracked
+// rather than awaited, and everything that needs them finished waits here.
+/// Loads the module that decides what a plugin package *is*.
+///
+/// The host itself knows one shape: a module exporting `activate`. Anything
+/// else — a Cordis plugin mounted into a shared composition realm, say — is a
+/// different answer to the same question, and the host has no business knowing
+/// which answers exist. So rebon names the module that does, and this loads it.
+///
+/// The module exports `createLoader({ next })` and returns `{ load, unload }`;
+/// `next` is the built-in loader, so an adapter that does not recognise a
+/// package hands it back rather than reimplementing it.
+export async function resolveLoader(specifier, error) {
+  if (!specifier) return {};
+  const url = specifier.startsWith('file:') ? specifier : pathToFileURL(specifier).href;
+  const module = await import(url);
+  if (typeof module.createLoader !== 'function') {
+    throw new ProtocolError('loader_invalid', `${specifier} exports no createLoader`);
+  }
+  const seams = await module.createLoader({ next: loadPlugin });
+  if (typeof seams?.load !== 'function') {
+    throw new ProtocolError('loader_invalid', `${specifier} produced no load function`);
+  }
+  return seams;
+}
+
+export async function runHost({ input, output, error, loader }) {
+  const decoder = new NdjsonDecoder();
+  const writer = new SerializedWriter(output);
+  const host = new PluginHost(writer, loader ?? {});
+  const running = new Set();
+  let fatal = null;
+  const track = (promise) => {
+    const tracked = promise.catch((cause) => { fatal ??= cause; }).finally(() => running.delete(tracked));
+    running.add(tracked);
+  };
+  // Draining rather than a single `Promise.all`: a dispatch that is still
+  // running can schedule another one, and the process must not exit under it.
+  const quiesce = async () => { while (running.size > 0) await Promise.all([...running]); };
+  try {
+    for await (const chunk of input) {
+      for (const frame of decoder.push(chunk)) {
+        if (fatal) throw fatal;
+        if (host.shuttingDown) throw new ProtocolError('frame_after_shutdown', 'frame received after shutdown');
+        track(host.accept(frame));
+      }
+      if (fatal) throw fatal;
+      if (host.shuttingDown) { await quiesce(); if (fatal) throw fatal; return 0; }
+    }
+    decoder.finish();
+    await quiesce();
+    if (fatal) throw fatal;
+    diagnostic(error, 'connection_lost', 'stdin reached EOF before successful shutdown');
+    return 3;
+  } catch (cause) {
+    // Terminals already owed still have to reach stdout: a caller waiting on
+    // one is not made whole by the host exiting with a diagnosis.
+    await quiesce();
+    const code = cause?.code ?? 'host_failure';
+    diagnostic(error, code, cause?.message ?? 'host failed');
+    return code === 'write_error' ? 4 : 2;
+  }
+}
+
+/// A rejection nobody handled, said out loud instead of swallowed, and
+/// attributed where the async chain reaches back to an entry.
+///
+/// Node does not stop this process for one, and nothing else looks either: a
+/// plugin could start an async task, have it fail, and leave no trace anywhere
+/// rebon reads.
+///
+/// A failed promise does not carry who created it, but `plugin/load` runs
+/// inside a store that survives timers, microtasks and awaits, so this handler
+/// reads the owner straight out of it. What escapes the chain — through an
+/// `EventEmitter`, a native callback or a third-party library — is still
+/// `unattributed`, which is the truthful answer and is kept distinct from a
+/// wrong one.
+///
+/// It never exits. A stray rejection in one plugin must not take down a host
+/// other plugins are being served from; a load still in flight is failed by its
+/// own path instead, which is the caller's to run.
+export function installRejectionDiagnostic(stream) {
+  process.on('unhandledRejection', (reason) => {
+    const first = String(reason?.stack ?? reason ?? '').split('\n')[0];
+    const owner = currentOwner();
+    if (owner === undefined) {
+      diagnostic(stream, 'unhandled_rejection', `unattributed: ${first}`);
+      return;
+    }
+    // `loading` says which of the two this is. While a load is in flight the
+    // entry did not install correctly and nothing depends on it yet, so the
+    // load fails and the composition skips it with a reason. Afterwards the
+    // plugin stays ready: a load that already succeeded cannot be un-failed,
+    // and tearing down a plane other entries serve from would cost far more
+    // than the one bad promise.
+    if (owner.loading) {
+      owner.rejection = first;
+      diagnostic(stream, 'unhandled_rejection', `plugin=${owner.entry} during load: ${first}`);
+      return;
+    }
+    diagnostic(stream, 'unhandled_rejection', `plugin=${owner.entry}: ${first}`);
+  });
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  installRejectionDiagnostic(process.stderr);
+  const flag = process.argv.indexOf('--loader');
+  const specifier = flag >= 0 ? process.argv[flag + 1] : process.env.REBON_PLUGIN_LOADER;
+  let loader;
+  try {
+    loader = await resolveLoader(specifier, process.stderr);
+  } catch (cause) {
+    // A host that cannot build the loader rebon asked for must not fall back to
+    // the built-in one: it would load a different set of plugins than the one
+    // rebon believes it asked for, and say nothing.
+    diagnostic(process.stderr, cause?.code ?? 'loader_failure', cause?.message ?? 'loader failed');
+    process.exitCode = 2;
+  }
+  if (loader !== undefined) {
+    process.exitCode = await runHost({
+      input: process.stdin, output: process.stdout, error: process.stderr, loader,
+    });
+  }
+}

package/payload/plugin-host/src/framing.mjs

@@ -1,113 +1,113 @@
-import { MAX_FRAME_BYTES, ProtocolError, validateEnvelope } from './protocol.mjs';
-import { parseEnvelopeJson } from './json.mjs';
-
-export class FramingError extends ProtocolError {}
-
-export class NdjsonDecoder {
-  #segments = []; #byteCount = 0; #failed = false; #copiedBytes = 0;
-  constructor(maxFrameBytes = MAX_FRAME_BYTES) { this.maxFrameBytes = maxFrameBytes; }
-  get stats() { return Object.freeze({ retained_bytes: this.#byteCount, copied_bytes: this.#copiedBytes }); }
-  push(chunk) {
-    if (this.#failed) throw new FramingError('poisoned', 'decoder is poisoned');
-    if (!Buffer.isBuffer(chunk) && !(chunk instanceof Uint8Array)) return this.#fail('wrong_chunk', 'input chunk must be bytes');
-    const input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
-    const frames = [];
-    let start = 0;
-    for (let index = 0; index < input.length; index++) {
-      if (input[index] !== 0x0a) continue;
-      this.#append(input.subarray(start, index));
-      let bytes = this.#join();
-      this.#segments = []; this.#byteCount = 0;
-      if (bytes.at(-1) === 0x0d) bytes = bytes.subarray(0, -1);
-      if (bytes.length > this.maxFrameBytes) return this.#fail('frame_too_large', `frame exceeds ${this.maxFrameBytes} bytes`);
-      if (bytes.length === 0) return this.#fail('empty_frame', 'NDJSON frame is empty');
-      if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
-        return this.#fail('utf8_bom', 'UTF-8 BOM is not permitted');
-      }
-      try {
-        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
-        frames.push(parseEnvelopeJson(text));
-      } catch (error) {
-        if (error instanceof ProtocolError) return this.#fail(error.code, error.message);
-        return this.#fail('invalid_utf8', 'frame is not valid UTF-8');
-      }
-      start = index + 1;
-    }
-    this.#append(input.subarray(start));
-    if (this.#byteCount > this.maxFrameBytes
-        && !(this.#byteCount === this.maxFrameBytes + 1 && this.#lastByte() === 0x0d)) {
-      return this.#fail('frame_too_large', `frame exceeds ${this.maxFrameBytes} bytes`);
-    }
-    return frames;
-  }
-  finish() {
-    if (this.#failed) throw new FramingError('poisoned', 'decoder is poisoned');
-    if (this.#byteCount) return this.#fail('incomplete_frame', `EOF with unterminated ${this.#byteCount}-byte frame`);
-  }
-  #append(bytes) {
-    if (!bytes.length) return;
-    const copy = Buffer.from(bytes);
-    this.#segments.push(copy); this.#byteCount += copy.length; this.#copiedBytes += copy.length;
-  }
-  #join() {
-    if (this.#segments.length === 1) return this.#segments[0];
-    this.#copiedBytes += this.#byteCount;
-    return Buffer.concat(this.#segments, this.#byteCount);
-  }
-  #lastByte() { return this.#segments.at(-1)?.at(-1); }
-  #fail(code, message) { this.#failed = true; this.#segments = []; this.#byteCount = 0; throw new FramingError(code, message); }
-}
-
-export function encodeFrame(value, maxFrameBytes = MAX_FRAME_BYTES) {
-  const normalized = validateEnvelope(value);
-  let text;
-  try { text = JSON.stringify(normalized); } catch { throw new FramingError('encode_error', 'envelope cannot be encoded'); }
-  const bytes = Buffer.from(text);
-  if (bytes.length > maxFrameBytes) throw new FramingError('frame_too_large', `frame exceeds ${maxFrameBytes} bytes`);
-  return Buffer.concat([bytes, Buffer.from('\n')]);
-}
-
-export class SerializedWriter {
-  #tail = Promise.resolve(); #error;
-  constructor(stream, maxFrameBytes = MAX_FRAME_BYTES) { this.stream = stream; this.maxFrameBytes = maxFrameBytes; }
-  send(value) {
-    if (this.#error) return Promise.reject(this.#error);
-    const bytes = encodeFrame(value, this.maxFrameBytes);
-    const operation = this.#tail.then(() => {
-      if (this.#error) throw this.#error;
-      return this.#write(bytes);
-    });
-    this.#tail = operation.catch((error) => { this.#error ??= error; });
-    return operation;
-  }
-  async flush() { await this.#tail; if (this.#error) throw this.#error; }
-  #write(bytes) {
-    return new Promise((resolve, reject) => {
-      let callbackDone = false; let accepted; let drainSeen = false; let settled = false;
-      const cleanup = () => { this.stream.removeListener('error', onError); this.stream.removeListener('drain', onDrain); };
-      const fail = (cause) => {
-        if (settled) return;
-        settled = true; cleanup();
-        const error = cause instanceof FramingError ? cause
-          : new FramingError('write_error', `protocol output failed: ${cause?.code ?? 'stream error'}`);
-        this.#error ??= error; reject(error);
-      };
-      const complete = () => {
-        if (settled || accepted === undefined || !callbackDone || (!accepted && !drainSeen)) return;
-        settled = true; cleanup(); resolve();
-      };
-      const onError = (error) => fail(error);
-      const onDrain = () => { drainSeen = true; complete(); };
-      this.stream.once('error', onError);
-      this.stream.once('drain', onDrain);
-      try {
-        accepted = this.stream.write(bytes, (error) => {
-          if (error) { setImmediate(() => fail(error)); return; }
-          callbackDone = true; complete();
-        });
-        if (accepted) this.stream.removeListener('drain', onDrain);
-        complete();
-      } catch (error) { fail(error); }
-    });
-  }
-}
+import { MAX_FRAME_BYTES, ProtocolError, validateEnvelope } from './protocol.mjs';
+import { parseEnvelopeJson } from './json.mjs';
+
+export class FramingError extends ProtocolError {}
+
+export class NdjsonDecoder {
+  #segments = []; #byteCount = 0; #failed = false; #copiedBytes = 0;
+  constructor(maxFrameBytes = MAX_FRAME_BYTES) { this.maxFrameBytes = maxFrameBytes; }
+  get stats() { return Object.freeze({ retained_bytes: this.#byteCount, copied_bytes: this.#copiedBytes }); }
+  push(chunk) {
+    if (this.#failed) throw new FramingError('poisoned', 'decoder is poisoned');
+    if (!Buffer.isBuffer(chunk) && !(chunk instanceof Uint8Array)) return this.#fail('wrong_chunk', 'input chunk must be bytes');
+    const input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    const frames = [];
+    let start = 0;
+    for (let index = 0; index < input.length; index++) {
+      if (input[index] !== 0x0a) continue;
+      this.#append(input.subarray(start, index));
+      let bytes = this.#join();
+      this.#segments = []; this.#byteCount = 0;
+      if (bytes.at(-1) === 0x0d) bytes = bytes.subarray(0, -1);
+      if (bytes.length > this.maxFrameBytes) return this.#fail('frame_too_large', `frame exceeds ${this.maxFrameBytes} bytes`);
+      if (bytes.length === 0) return this.#fail('empty_frame', 'NDJSON frame is empty');
+      if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return this.#fail('utf8_bom', 'UTF-8 BOM is not permitted');
+      }
+      try {
+        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+        frames.push(parseEnvelopeJson(text));
+      } catch (error) {
+        if (error instanceof ProtocolError) return this.#fail(error.code, error.message);
+        return this.#fail('invalid_utf8', 'frame is not valid UTF-8');
+      }
+      start = index + 1;
+    }
+    this.#append(input.subarray(start));
+    if (this.#byteCount > this.maxFrameBytes
+        && !(this.#byteCount === this.maxFrameBytes + 1 && this.#lastByte() === 0x0d)) {
+      return this.#fail('frame_too_large', `frame exceeds ${this.maxFrameBytes} bytes`);
+    }
+    return frames;
+  }
+  finish() {
+    if (this.#failed) throw new FramingError('poisoned', 'decoder is poisoned');
+    if (this.#byteCount) return this.#fail('incomplete_frame', `EOF with unterminated ${this.#byteCount}-byte frame`);
+  }
+  #append(bytes) {
+    if (!bytes.length) return;
+    const copy = Buffer.from(bytes);
+    this.#segments.push(copy); this.#byteCount += copy.length; this.#copiedBytes += copy.length;
+  }
+  #join() {
+    if (this.#segments.length === 1) return this.#segments[0];
+    this.#copiedBytes += this.#byteCount;
+    return Buffer.concat(this.#segments, this.#byteCount);
+  }
+  #lastByte() { return this.#segments.at(-1)?.at(-1); }
+  #fail(code, message) { this.#failed = true; this.#segments = []; this.#byteCount = 0; throw new FramingError(code, message); }
+}
+
+export function encodeFrame(value, maxFrameBytes = MAX_FRAME_BYTES) {
+  const normalized = validateEnvelope(value);
+  let text;
+  try { text = JSON.stringify(normalized); } catch { throw new FramingError('encode_error', 'envelope cannot be encoded'); }
+  const bytes = Buffer.from(text);
+  if (bytes.length > maxFrameBytes) throw new FramingError('frame_too_large', `frame exceeds ${maxFrameBytes} bytes`);
+  return Buffer.concat([bytes, Buffer.from('\n')]);
+}
+
+export class SerializedWriter {
+  #tail = Promise.resolve(); #error;
+  constructor(stream, maxFrameBytes = MAX_FRAME_BYTES) { this.stream = stream; this.maxFrameBytes = maxFrameBytes; }
+  send(value) {
+    if (this.#error) return Promise.reject(this.#error);
+    const bytes = encodeFrame(value, this.maxFrameBytes);
+    const operation = this.#tail.then(() => {
+      if (this.#error) throw this.#error;
+      return this.#write(bytes);
+    });
+    this.#tail = operation.catch((error) => { this.#error ??= error; });
+    return operation;
+  }
+  async flush() { await this.#tail; if (this.#error) throw this.#error; }
+  #write(bytes) {
+    return new Promise((resolve, reject) => {
+      let callbackDone = false; let accepted; let drainSeen = false; let settled = false;
+      const cleanup = () => { this.stream.removeListener('error', onError); this.stream.removeListener('drain', onDrain); };
+      const fail = (cause) => {
+        if (settled) return;
+        settled = true; cleanup();
+        const error = cause instanceof FramingError ? cause
+          : new FramingError('write_error', `protocol output failed: ${cause?.code ?? 'stream error'}`);
+        this.#error ??= error; reject(error);
+      };
+      const complete = () => {
+        if (settled || accepted === undefined || !callbackDone || (!accepted && !drainSeen)) return;
+        settled = true; cleanup(); resolve();
+      };
+      const onError = (error) => fail(error);
+      const onDrain = () => { drainSeen = true; complete(); };
+      this.stream.once('error', onError);
+      this.stream.once('drain', onDrain);
+      try {
+        accepted = this.stream.write(bytes, (error) => {
+          if (error) { setImmediate(() => fail(error)); return; }
+          callbackDone = true; complete();
+        });
+        if (accepted) this.stream.removeListener('drain', onDrain);
+        complete();
+      } catch (error) { fail(error); }
+    });
+  }
+}