@fireemu/linux-x64 0.7.1 → 0.9.0

package/README.md

@@ -1,7 +1,7 @@
 # @fireemu/linux-x64
 
 The [fireemu](https://www.npmjs.com/package/fireemu) daemon built for `linux-x64`
-(Rust target `x86_64-unknown-linux-musl`), version 0.7.1.
+(Rust target `x86_64-unknown-linux-musl`), version 0.9.0.
 
 Statically linked against musl: any glibc or musl distribution, including distroless and Alpine.
 

package/bin/runner-node/blocking-error.mjs

@@ -29,18 +29,33 @@ const safeMessage = (value) =>
   !/\p{Cc}|[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u.test(value);
 
 export function blockingFailure(error, HttpsErrors) {
-  const code = typeof error?.code === "string" ? functionErrorCodes.get(error.code) : undefined;
-  if (
-    !Array.isArray(HttpsErrors) ||
-    !HttpsErrors.some((HttpsError) =>
-      typeof HttpsError === "function" && error instanceof HttpsError
-    ) ||
-    !code ||
-    error?.httpErrorCode?.canonicalName !== code.canonicalName ||
-    error?.httpErrorCode?.status !== code.status ||
-    !safeMessage(error?.message)
-  ) {
+  try {
+    if (
+      !Array.isArray(HttpsErrors) ||
+      !HttpsErrors.some((HttpsError) =>
+        typeof HttpsError === "function" && error instanceof HttpsError
+      )
+    ) {
+      return unavailable;
+    }
+    // Read each potentially user-defined accessor once. In particular, validating
+    // one message and returning a second getter result can leak an unsafe message.
+    const rawCode = error.code;
+    const metadata = error.httpErrorCode;
+    const message = error.message;
+    const code = typeof rawCode === "string" ? functionErrorCodes.get(rawCode) : undefined;
+    if (
+      !code ||
+      metadata?.canonicalName !== code.canonicalName ||
+      metadata?.status !== code.status ||
+      !safeMessage(message)
+    ) {
+      return unavailable;
+    }
+    return { ...code, message };
+  } catch {
+    // Error objects, proxies and even instanceof hooks can throw. Their details
+    // must not replace the fixed public fallback or break the HTTP error path.
     return unavailable;
   }
-  return { ...code, message: error.message };
 }

package/bin/runner-node/blocking-event.mjs

@@ -0,0 +1,224 @@
+// The event a blocking function receives, built as Identity Platform's delivery builds it: the
+// request carries an unsigned blocking token (`{"data":{"jwt":…}}`, the official Auth
+// emulator's form), and the codebase's own firebase-functions parsers turn it into the user
+// record and the event context, exactly as the SDK's wrapped handler does before it calls the
+// handler (firebase-functions `common/providers/identity` `wrapHandler`). The runner keeps its
+// own response and error handling (blocking-response.mjs, blocking-error.mjs).
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+/** A blocking token's payload, decoded without verification as the SDK does under the emulator. */
+export function decodeBlockingToken(jwt) {
+  if (typeof jwt !== "string") throw new TypeError("the blocking token is not a string");
+  const parts = jwt.split(".");
+  if (parts.length !== 3) throw new TypeError("the blocking token is not a JWT");
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+  } catch {
+    throw new TypeError("the blocking token's payload is not JSON");
+  }
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new TypeError("the blocking token's payload is not an object");
+  }
+  // The SDK's unsafeDecodeAuthBlockingToken names the subject as the uid.
+  payload.uid = payload.sub;
+  return payload;
+}
+
+/**
+ * The handler's `{user, context}` for a request that carries a blocking token, or undefined
+ * for one that does not. `parsers` are the SDK's `parseAuthUserRecord` and
+ * `parseAuthEventContext`; the user record is parsed for the user events only.
+ */
+export function blockingEvent(body, parsers, projectId) {
+  const jwt = body?.data?.jwt;
+  if (jwt === undefined) return undefined;
+  const decoded = decodeBlockingToken(jwt);
+  const user =
+    decoded.event_type === "beforeCreate" || decoded.event_type === "beforeSignIn"
+      ? parsers.parseAuthUserRecord(decoded.user_record)
+      : undefined;
+  return { user, context: parsers.parseAuthEventContext(decoded, projectId) };
+}
+
+function packageRoot(require) {
+  let root = dirname(require.resolve("firebase-functions"));
+  for (;;) {
+    const candidate = join(root, "package.json");
+    if (existsSync(candidate) && JSON.parse(readFileSync(candidate, "utf8")).name === "firebase-functions")
+      return root;
+    const parent = dirname(root);
+    if (parent === root) throw new Error("cannot locate the firebase-functions package root");
+    root = parent;
+  }
+}
+
+/**
+ * The SDK's parsers from the codebase's firebase-functions (`lib/common/providers/identity.js`,
+ * not in its public exports), or null when that SDK does not expose both there; the runner then
+ * uses [`portedIdentityParsers`].
+ */
+export function loadIdentityParsers(require) {
+  try {
+    const identity = require(join(packageRoot(require), "lib", "common", "providers", "identity.js"));
+    const { parseAuthUserRecord, parseAuthEventContext } = identity;
+    if (typeof parseAuthUserRecord !== "function" || typeof parseAuthEventContext !== "function")
+      return null;
+    return { parseAuthUserRecord, parseAuthEventContext };
+  } catch {
+    return null;
+  }
+}
+
+// A port of firebase-functions 7.3.2 `lib/common/providers/identity.js` (MIT License, Copyright
+// Google LLC): the event a handler receives when the codebase's firebase-functions does not
+// expose its own parsers. Identity Platform delivers the same token to every SDK version, so
+// the event is built as that SDK builds it rather than refused (an SDK's own parsers are used
+// whenever they can be loaded).
+const EVENT_MAPPING = {
+  beforeCreate: "providers/cloud.auth/eventTypes/user.beforeCreate",
+  beforeSignIn: "providers/cloud.auth/eventTypes/user.beforeSignIn",
+  beforeSendEmail: "providers/cloud.auth/eventTypes/user.beforeSendEmail",
+  beforeSendSms: "providers/cloud.auth/eventTypes/user.beforeSendSms",
+};
+
+const utcDate = (value) => (value ? new Date(value).toUTCString() : null);
+
+function parseMetadata(metadata) {
+  return {
+    creationTime: utcDate(metadata?.creation_time),
+    lastSignInTime: utcDate(metadata?.last_sign_in_time),
+  };
+}
+
+function parseProviderData(providerData) {
+  return providerData.map((provider) => ({
+    uid: provider.uid,
+    displayName: provider.display_name,
+    email: provider.email,
+    photoURL: provider.photo_url,
+    providerId: provider.provider_id,
+    phoneNumber: provider.phone_number,
+  }));
+}
+
+function parseDate(seconds) {
+  if (!seconds) return null;
+  const date = new Date(seconds * 1000);
+  return isNaN(date.getTime()) ? null : date.toUTCString();
+}
+
+function parseMultiFactor(multiFactor) {
+  if (!multiFactor) return null;
+  const enrolledFactors = [];
+  for (const factor of multiFactor.enrolled_factors || []) {
+    if (!factor.uid) throw new Error("INTERNAL ASSERT FAILED: Invalid multi-factor info response");
+    enrolledFactors.push({
+      uid: factor.uid,
+      factorId: factor.phone_number ? factor.factor_id || "phone" : factor.factor_id,
+      displayName: factor.display_name,
+      enrollmentTime: factor.enrollment_time ? new Date(factor.enrollment_time).toUTCString() : null,
+      phoneNumber: factor.phone_number,
+    });
+  }
+  return enrolledFactors.length > 0 ? { enrolledFactors } : null;
+}
+
+function parseAuthUserRecord(record) {
+  if (!record?.uid) throw new Error("INTERNAL ASSERT FAILED: Invalid user response");
+  return {
+    uid: record.uid,
+    email: record.email,
+    emailVerified: record.email_verified,
+    displayName: record.display_name,
+    photoURL: record.photo_url,
+    phoneNumber: record.phone_number,
+    disabled: record.disabled || false,
+    metadata: parseMetadata(record.metadata),
+    providerData: parseProviderData(record.provider_data),
+    passwordHash: record.password_hash,
+    passwordSalt: record.password_salt,
+    customClaims: record.custom_claims,
+    tenantId: record.tenant_id,
+    tokensValidAfterTime: parseDate(record.tokens_valid_after_time),
+    multiFactor: parseMultiFactor(record.multi_factor),
+  };
+}
+
+function parseAdditionalUserInfo(decoded) {
+  let profile;
+  let username;
+  if (decoded.raw_user_info) {
+    try {
+      profile = JSON.parse(decoded.raw_user_info);
+    } catch {
+      // The SDK only logs an unparsable profile.
+    }
+  }
+  if (profile) {
+    if (decoded.sign_in_method === "github.com") username = profile.login;
+    if (decoded.sign_in_method === "twitter.com") username = profile.screen_name;
+  }
+  return {
+    providerId: decoded.sign_in_method === "emailLink" ? "password" : decoded.sign_in_method,
+    profile,
+    username,
+    isNewUser: decoded.event_type === "beforeCreate",
+    recaptchaScore: decoded.recaptcha_score,
+    email: decoded.email,
+    phoneNumber: decoded.phone_number,
+  };
+}
+
+function parseAuthCredential(decoded, time) {
+  if (
+    !decoded.sign_in_attributes &&
+    !decoded.oauth_id_token &&
+    !decoded.oauth_access_token &&
+    !decoded.oauth_refresh_token
+  ) {
+    return null;
+  }
+  return {
+    claims: decoded.sign_in_attributes,
+    idToken: decoded.oauth_id_token,
+    accessToken: decoded.oauth_access_token,
+    refreshToken: decoded.oauth_refresh_token,
+    expirationTime: decoded.oauth_expires_in
+      ? new Date(time + decoded.oauth_expires_in * 1000).toUTCString()
+      : undefined,
+    secret: decoded.oauth_token_secret,
+    providerId: decoded.sign_in_method === "emailLink" ? "password" : decoded.sign_in_method,
+    signInMethod: decoded.sign_in_method,
+  };
+}
+
+function parseAuthEventContext(decoded, projectId, time = new Date().getTime()) {
+  const eventType =
+    (EVENT_MAPPING[decoded.event_type] || decoded.event_type) +
+    (decoded.sign_in_method ? `:${decoded.sign_in_method}` : "");
+  return {
+    locale: decoded.locale,
+    ipAddress: decoded.ip_address,
+    userAgent: decoded.user_agent,
+    eventId: decoded.event_id,
+    eventType,
+    authType: decoded.user_record ? "USER" : "UNAUTHENTICATED",
+    resource: {
+      service: "identitytoolkit.googleapis.com",
+      name: decoded.tenant_id
+        ? `projects/${projectId}/tenants/${decoded.tenant_id}`
+        : `projects/${projectId}`,
+    },
+    timestamp: new Date(decoded.iat * 1000).toUTCString(),
+    additionalUserInfo: parseAdditionalUserInfo(decoded),
+    credential: parseAuthCredential(decoded, time),
+    emailType: decoded.email_type,
+    smsType: decoded.sms_type,
+    params: {},
+  };
+}
+
+/** The ported parsers ([`loadIdentityParsers`] prefers the codebase's own). */
+export const portedIdentityParsers = Object.freeze({ parseAuthUserRecord, parseAuthEventContext });

package/bin/runner-node/blocking-response.mjs

@@ -19,7 +19,10 @@ const disallowedClaims = [
 const claimsMaxPayloadSize = 1000;
 
 function validateClaims(name, claims, HttpsError) {
-  if (!claims) return;
+  if (claims === undefined || claims === null) return;
+  if (typeof claims !== "object" || Array.isArray(claims)) {
+    throw new HttpsError("invalid-argument", `The ${name} response must be an object or null.`);
+  }
   const invalid = disallowedClaims.filter((claim) =>
     Object.prototype.hasOwnProperty.call(claims, claim),
   );
@@ -49,8 +52,9 @@ function validateBlockingResult(value, eventType, HttpsError) {
     throw new HttpsError("invalid-argument", "The userRecord response must be an object.");
   }
   validateClaims("customClaims", authRequest.customClaims, HttpsError);
-  if (!String(eventType).includes("beforeSignIn") || !authRequest.sessionClaims) return;
+  if (!String(eventType).includes("beforeSignIn")) return;
   validateClaims("sessionClaims", authRequest.sessionClaims, HttpsError);
+  if (authRequest.sessionClaims === undefined || authRequest.sessionClaims === null) return;
   const combined = { ...authRequest.customClaims, ...authRequest.sessionClaims };
   if (JSON.stringify(combined).length > claimsMaxPayloadSize) {
     throw new HttpsError(
@@ -60,26 +64,101 @@ function validateBlockingResult(value, eventType, HttpsError) {
   }
 }
 
+// Validate the representation that will actually cross the HTTP boundary. Callback
+// objects can contain getters/toJSON and can remain aliased to user code. Evaluating
+// those objects again after validation can change claims, sizes, or the update mask.
+// JSON materialization is deliberately before claim checks; the returned value has
+// no user getters or callable toJSON hooks and shares no objects with the callback.
+function snapshotResponse(candidate, HttpsError) {
+  let snapshot;
+  try {
+    snapshot = JSON.parse(JSON.stringify(candidate));
+  } catch {
+    // Do not include a thrown value, circular-object path, or credential in the error.
+    throw new HttpsError("invalid-argument", "The blocking response must be JSON serializable.");
+  }
+  if (
+    !snapshot ||
+    typeof snapshot !== "object" ||
+    Array.isArray(snapshot) ||
+    !Object.prototype.hasOwnProperty.call(snapshot, "userRecord") ||
+    !snapshot.userRecord ||
+    typeof snapshot.userRecord !== "object" ||
+    Array.isArray(snapshot.userRecord)
+  ) {
+    throw new HttpsError("invalid-argument", "The userRecord response must be an object.");
+  }
+  return snapshot;
+}
+
+function freezeResponse(snapshot) {
+  const pending = [snapshot];
+  while (pending.length > 0) {
+    const value = pending.pop();
+    if (value && typeof value === "object") {
+      for (const child of Object.values(value)) pending.push(child);
+      Object.freeze(value);
+    }
+  }
+  return snapshot;
+}
+
+// The customClaims text as the function's JSON.stringify gives it: what the Functions SDK sends
+// Identity Platform, which production reads back as `customAttributes` with its key order
+// (AUTH-TENANT-BLOCKING recording 2026-09-28). The runner owns this member; the daemon uses the
+// text only when it parses to the claims it applies.
+const CUSTOM_CLAIMS_TEXT = "fireemuCustomClaimsText";
+
+function attachCustomClaimsText(snapshot) {
+  delete snapshot[CUSTOM_CLAIMS_TEXT];
+  // validateBlockingResult has admitted only an object, null or no claims.
+  const claims = snapshot.userRecord.customClaims;
+  if (claims != null) snapshot[CUSTOM_CLAIMS_TEXT] = JSON.stringify(claims);
+  return snapshot;
+}
+
 export function blockingResult(value, eventType, HttpsError) {
+  // Preserve the runner's established no-result behaviour.
   if (!value || typeof value !== "object") return {};
-  validateBlockingResult(value, eventType, HttpsError);
-  if (Object.prototype.hasOwnProperty.call(value, "userRecord")) return value;
-  const userRecord = {};
-  const updateMask = [];
-  for (const [publicName, wireName] of [
-    ["displayName", "displayName"],
-    ["photoURL", "photoUrl"],
-    ["disabled", "disabled"],
-    ["emailVerified", "emailVerified"],
-    ["customClaims", "customClaims"],
-    ["sessionClaims", "sessionClaims"],
-  ]) {
-    if (Object.prototype.hasOwnProperty.call(value, publicName)) {
-      userRecord[wireName] = value[publicName];
-      updateMask.push(wireName);
+  if (Array.isArray(value)) {
+    throw new HttpsError("invalid-argument", "The userRecord response must be an object.");
+  }
+  let candidate;
+  try {
+    if (Object.prototype.hasOwnProperty.call(value, "userRecord")) {
+      // Preserve SDK wire-envelope extensions, but never return the caller's object.
+      candidate = value;
+    } else {
+      const userRecord = {};
+      const updateMask = [];
+      // Each field goes under its public name, as the Functions SDK's generateResponsePayload
+      // sends it: Identity Platform does not apply `photoURL` (it reads `photoUrl`), so a
+      // function's photoURL is ignored (AUTH-TENANT-BLOCKING recording 2026-09-28,
+      // ordering#lookup-profile; the official Auth emulator reads `photoUrl` only too).
+      for (const name of [
+        "displayName",
+        "photoURL",
+        "disabled",
+        "emailVerified",
+        "customClaims",
+        "sessionClaims",
+      ]) {
+        if (Object.prototype.hasOwnProperty.call(value, name)) {
+          const field = value[name];
+          // Like the Functions SDK's getUpdateMask, undefined means no update;
+          // null, false, and an empty string are still explicit updates.
+          if (field === undefined) continue;
+          userRecord[name] = field;
+          updateMask.push(name);
+        }
+      }
+      if (updateMask.length === 0) return {};
+      candidate = { userRecord: { ...userRecord, updateMask: updateMask.join(",") } };
     }
+  } catch {
+    throw new HttpsError("invalid-argument", "The blocking response could not be read.");
   }
-  return updateMask.length > 0
-    ? { userRecord: { ...userRecord, updateMask: updateMask.join(",") } }
-    : {};
+  const snapshot = snapshotResponse(candidate, HttpsError);
+  validateBlockingResult(snapshot, eventType, HttpsError);
+  return freezeResponse(attachCustomClaimsText(snapshot));
 }

package/bin/runner-node/diagnostic-output.mjs

@@ -0,0 +1,259 @@
+// Bounded admission for direct stderr (and redirected user stdout) writes.
+// The native Writable owns byte ordering and corking. Callback accounting adds
+// backpressure even when a native write completes synchronously.
+// This is not a process-wide sandbox: direct fd writes and replaced methods bypass it.
+import { performance } from 'node:perf_hooks';
+import { types } from 'node:util';
+
+const typedPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const viewGetters = Object.fromEntries(['buffer', 'byteOffset', 'byteLength'].map(key =>
+  [key, Object.getOwnPropertyDescriptor(typedPrototype, key).get]));
+const dataViewGetters = Object.fromEntries(['buffer', 'byteOffset', 'byteLength'].map(key =>
+  [key, Object.getOwnPropertyDescriptor(DataView.prototype, key).get]));
+function viewData(chunk) {
+  const getters = types.isDataView(chunk) ? dataViewGetters : viewGetters;
+  return { buffer: getters.buffer.call(chunk), offset: getters.byteOffset.call(chunk),
+    length: getters.byteLength.call(chunk) };
+}
+
+export const MAX_DIAGNOSTIC_BYTES = 8 * 1024 * 1024;
+export const MAX_DIAGNOSTIC_WRITES = 1024;
+export const MAX_DIAGNOSTIC_WAIT_MS = 30_000;
+export const DIAGNOSTIC_FINISH_MS = 1_000;
+
+export class DiagnosticOutputError extends Error {
+  constructor(reason) {
+    super(`runner diagnostic output failed (${reason})`);
+    this.name = 'DiagnosticOutputError';
+    this.code = 'ERR_FIREEMU_DIAGNOSTIC_OUTPUT';
+  }
+}
+
+function limit(value, maximum, name) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw new TypeError(`invalid diagnostic ${name}`);
+  }
+  return value;
+}
+
+export class DiagnosticWriter {
+  #stream;
+  #write;
+  #emit;
+  #highWaterMark;
+  #needsDrain = false;
+  #nativeBackpressure = false;
+  #drainScheduled = false;
+  #onError;
+  #maxBytes;
+  #maxWrites;
+  #waitMs;
+  #finishMs;
+  #defaultEncoding = 'utf8';
+  #pending = new Set();
+  #bytes = 0;
+  #failed = null;
+  #closing = false;
+  #closeAt = Infinity;
+  #timer = null;
+  #finishPromise;
+  #finishResolve;
+
+  constructor(stream, {
+    onError,
+    maxBytes = MAX_DIAGNOSTIC_BYTES,
+    maxWrites = MAX_DIAGNOSTIC_WRITES,
+    waitMs = MAX_DIAGNOSTIC_WAIT_MS,
+    finishMs = DIAGNOSTIC_FINISH_MS,
+  } = {}) {
+    if (typeof stream?.write !== 'function' || typeof stream?.on !== 'function' ||
+        typeof stream?.emit !== 'function' ||
+        typeof onError !== 'function') throw new TypeError('diagnostic stream and onError required');
+    this.#stream = stream;
+    this.#write = stream.write.bind(stream);
+    this.#emit = stream.emit.bind(stream);
+    this.#onError = onError;
+    this.#maxBytes = limit(maxBytes, MAX_DIAGNOSTIC_BYTES, 'bytes');
+    this.#maxWrites = limit(maxWrites, MAX_DIAGNOSTIC_WRITES, 'writes');
+    this.#waitMs = limit(waitMs, MAX_DIAGNOSTIC_WAIT_MS, 'wait');
+    this.#finishMs = limit(finishMs, DIAGNOSTIC_FINISH_MS, 'finish wait');
+    const nativeHighWaterMark = stream.writableHighWaterMark;
+    this.#highWaterMark = Math.min(this.#maxBytes,
+      Number.isSafeInteger(nativeHighWaterMark) && nativeHighWaterMark > 0
+        ? nativeHighWaterMark : 64 * 1024);
+    // Native drain can fire before write callbacks. Do not tell a producer to
+    // resume while our callback reservations still fill the budget. Coalesce
+    // it with logical backpressure and emit only after BOTH have cleared.
+    stream.emit = (event, ...args) => {
+      if (event !== 'drain') return this.#emit(event, ...args);
+      this.#nativeBackpressure = false;
+      this.#requestDrain();
+      return (stream.listenerCount?.('drain') ?? 0) > 0;
+    };
+    // Retain the error listener after failure: an error event may follow its callback.
+    stream.on('error', () => this.#fail('stream error'));
+    stream.on('close', () => this.#fail('stream closed'));
+    stream.on('finish', () => this.#fail('stream ended'));
+  }
+
+  get state() {
+    return Object.freeze({ pendingBytes: this.#bytes, pendingWrites: this.#pending.size,
+      failed: this.#failed !== null, closing: this.#closing });
+  }
+
+  setDefaultEncoding(encoding) {
+    if (typeof encoding !== 'string' || !Buffer.isEncoding(encoding)) {
+      throw new TypeError('invalid diagnostic encoding');
+    }
+    this.#defaultEncoding = encoding;
+    return this;
+  }
+
+  write(chunk, encoding, callback) {
+    if (typeof encoding === 'function') { callback = encoding; encoding = undefined; }
+    if (callback !== undefined && callback !== null && typeof callback !== 'function') {
+      throw new TypeError('diagnostic write callback must be a function');
+    }
+    if (this.#failed || this.#closing) {
+      if (callback) process.nextTick(callback, this.#failed ?? new DiagnosticOutputError('closing'));
+      return false;
+    }
+    if (this.#expired()) { this.#fail('deadline'); return this.write(chunk, encoding, callback); }
+    let size, selectedEncoding, view;
+    if (typeof chunk === 'string') {
+      selectedEncoding = encoding || this.#defaultEncoding;
+      if (typeof selectedEncoding !== 'string' || !Buffer.isEncoding(selectedEncoding)) {
+        throw new TypeError('invalid diagnostic encoding');
+      }
+      size = Buffer.byteLength(chunk, selectedEncoding);
+    } else if (ArrayBuffer.isView(chunk)) {
+      view = viewData(chunk);
+      size = view.length;
+    } else {
+      throw new TypeError('diagnostic chunk must be a string or ArrayBuffer view');
+    }
+    // Include zero-length writes in the count: callbacks also retain memory.
+    if (this.#pending.size >= this.#maxWrites || this.#bytes + size > this.#maxBytes) {
+      this.#fail('pending limit');
+      return this.write(chunk, encoding, callback);
+    }
+    if (this.#stream.destroyed || this.#stream.writableEnded) {
+      this.#fail('stream unavailable');
+      return this.write(chunk, encoding, callback);
+    }
+    // Copy views before native queuing; later caller mutation cannot change admitted bytes.
+    // Strings are immutable. Encoding once also fixes accounting for hex/base64 inputs.
+    const payload = typeof chunk === 'string' ? Buffer.from(chunk, selectedEncoding) :
+      Buffer.from(new Uint8Array(view.buffer, view.offset, view.length));
+    // Buffer.byteLength(base64/hex) can be conservative for malformed input. Charge
+    // the bytes actually queued, after rejecting oversized allocation candidates above.
+    size = payload.length;
+    const entry = { size, at: performance.now(), callback };
+    this.#pending.add(entry);
+    this.#bytes += size;
+    let accepted;
+    try {
+      accepted = this.#write(payload, error => {
+        if (!this.#pending.has(entry)) return;
+        if (error) { this.#fail('write callback'); return; }
+        if (this.#expired()) { this.#fail('deadline'); return; }
+        this.#settle(entry);
+        this.#arm();
+      });
+    } catch {
+      this.#fail('write');
+      return false;
+    }
+    if (accepted !== true && accepted !== false) {
+      this.#fail('write return');
+      return false;
+    }
+    if (accepted === false) this.#nativeBackpressure = true;
+    const pressured = accepted === false || this.#bytes >= this.#highWaterMark ||
+      this.#pending.size >= this.#maxWrites;
+    if (pressured) this.#needsDrain = true;
+    this.#arm();
+    this.#requestDrain();
+    // Native false remains false. Native true may become false while completed
+    // writes still have deferred callbacks; otherwise a cooperative producer
+    // can exceed our limits before Node gets a turn to run those callbacks.
+    // In either case the write was accepted and must not be resent.
+    return this.#failed ? false : !pressured;
+  }
+
+  #settle(entry, error) {
+    if (!this.#pending.delete(entry)) return;
+    this.#bytes -= entry.size;
+    // User callbacks cannot reenter or corrupt admission bookkeeping. Like Writable,
+    // completion is asynchronous even with an inline write implementation in a test.
+    if (entry.callback) process.nextTick(entry.callback, error);
+    this.#requestDrain();
+  }
+
+  #requestDrain() {
+    if (this.#failed || this.#closing || !this.#needsDrain || this.#nativeBackpressure ||
+        this.#pending.size !== 0 || this.#drainScheduled) return;
+    this.#drainScheduled = true;
+    process.nextTick(() => {
+      this.#drainScheduled = false;
+      // A user write callback can enqueue new data before this notification.
+      if (this.#failed || this.#closing || !this.#needsDrain || this.#nativeBackpressure ||
+          this.#pending.size !== 0) return;
+      this.#needsDrain = false;
+      this.#emit('drain');
+    });
+  }
+
+  #expired() {
+    const oldest = this.#pending.values().next().value;
+    if (!oldest) return false;
+    const now = performance.now();
+    return now >= oldest.at + this.#waitMs || now >= this.#closeAt;
+  }
+
+  #fail(reason) {
+    if (this.#failed) return;
+    this.#failed = new DiagnosticOutputError(reason);
+    clearTimeout(this.#timer); this.#timer = null;
+    for (const entry of this.#pending) this.#settle(entry, this.#failed);
+    this.#finishResolve?.(false);
+    // Never write a diagnostic about this failure back into the failed stderr.
+    try { this.#onError(this.#failed); } catch { /* failure is already permanent */ }
+  }
+
+  #arm() {
+    clearTimeout(this.#timer); this.#timer = null;
+    if (this.#failed) return;
+    const oldest = this.#pending.values().next().value;
+    if (!oldest) { if (this.#closing) this.#finishResolve?.(true); return; }
+    const remaining = Math.min(oldest.at + this.#waitMs, this.#closeAt) - performance.now();
+    if (remaining <= 0) { this.#fail('deadline'); return; }
+    this.#timer = setTimeout(() => this.#arm(), Math.max(1, Math.ceil(remaining)));
+  }
+
+  // Flush already-admitted writes only; do not close fd2 or wait for user callbacks/tasks.
+  finish() {
+    if (this.#finishPromise) return this.#finishPromise;
+    this.#closing = true;
+    this.#closeAt = performance.now() + this.#finishMs;
+    this.#finishPromise = new Promise(resolve => { this.#finishResolve = resolve; });
+    if (this.#failed) this.#finishResolve(false); else this.#arm();
+    return this.#finishPromise;
+  }
+}
+
+// Install before loading a user codebase. Keep the original stream object, fd,
+// event listeners, cork/uncork and false-then-drain producer contract intact.
+// Own pending callbacks can add backpressure; native true is not always returned.
+export function installDiagnosticOutput(stream, options) {
+  const writer = new DiagnosticWriter(stream, options);
+  const setEncoding = stream.setDefaultEncoding?.bind(stream);
+  stream.write = writer.write.bind(writer);
+  if (setEncoding) stream.setDefaultEncoding = encoding => {
+    // Validate with the native API too; preserve its chaining return value.
+    const result = setEncoding(encoding);
+    writer.setDefaultEncoding(encoding);
+    return result;
+  };
+  return writer;
+}