@atolljs/node 0.1.4 → 0.1.5

package/dist/chunk-EEME4TDI.js

@@ -0,0 +1,697 @@
+// ../../src/log.ts
+var LEVELS = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, off: 5 };
+var THREAD = typeof WorkerGlobalScope !== "undefined" && self instanceof WorkerGlobalScope ? "worker" : "main";
+var consoleSink = ({ level, scope, message, data, thread, at }) => {
+  const prefix = `[${(at / 1e3).toFixed(2)}s ${thread}:${scope}]`;
+  const fn = level === "error" ? console.error : level === "warn" ? console.warn : level === "info" ? console.info : console.debug;
+  if (data !== void 0) fn(`${prefix} ${message}`, data);
+  else fn(`${prefix} ${message}`);
+};
+var minLevel = "info";
+var sink = consoleSink;
+function log(level, scope, message, data) {
+  if (LEVELS[level] < LEVELS[minLevel]) return;
+  sink({ level, scope, message, data, thread: THREAD, at: performance.now() });
+}
+function scoped(scope) {
+  return {
+    trace: (message, data) => log("trace", scope, message, data),
+    debug: (message, data) => log("debug", scope, message, data),
+    info: (message, data) => log("info", scope, message, data),
+    warn: (message, data) => log("warn", scope, message, data),
+    error: (message, data) => log("error", scope, message, data)
+  };
+}
+var fmtBytes = (bytes) => bytes >= 1 << 20 ? `${(bytes / (1 << 20)).toFixed(1)}MB` : bytes >= 1024 ? `${(bytes / 1024).toFixed(1)}KB` : `${bytes}B`;
+
+// ../../src/contract/sharedMemory.ts
+var memLog = scoped("memory");
+var codecTextEncoder = new TextEncoder();
+var codecTextDecoder = new TextDecoder();
+var CONNECTOR_FACTORIES = /* @__PURE__ */ new Map();
+function registerConnectorFactory(kind, factory) {
+  CONNECTOR_FACTORIES.set(kind, factory);
+}
+var TYPED_ARRAYS = {
+  Int32: Int32Array,
+  Float64: Float64Array,
+  BigInt64: BigInt64Array,
+  Uint8: Uint8Array
+};
+registerConnectorFactory("number", (d, ctx, byteOffset) => {
+  const view = new Float64Array(ctx.buffer, byteOffset, 1);
+  return { byteOffset, byteLength: d.byteLength, read: () => view[0], write: (v) => {
+    view[0] = v;
+  } };
+});
+registerConnectorFactory("boolean", (d, ctx, byteOffset) => {
+  const view = new Uint8Array(ctx.buffer, byteOffset, 1);
+  return { byteOffset, byteLength: d.byteLength, read: () => view[0] === 1, write: (v) => {
+    view[0] = v ? 1 : 0;
+  } };
+});
+for (const kind of Object.keys(TYPED_ARRAYS)) {
+  registerConnectorFactory(kind, (d, ctx, byteOffset) => {
+    const Ctor = TYPED_ARRAYS[kind];
+    const view = new Ctor(ctx.buffer, byteOffset, d.byteLength / Ctor.BYTES_PER_ELEMENT);
+    return { byteOffset, byteLength: d.byteLength, read: () => view, write: (v) => view.set(v) };
+  });
+}
+registerConnectorFactory("string", (d, ctx, byteOffset) => {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const capacity = d.byteLength - 4;
+  const lengthView = new Uint32Array(ctx.buffer, byteOffset, 1);
+  const writeBytes = (bytes) => {
+    if (bytes.byteLength > capacity) {
+      throw new Error(`Encoded value of ${bytes.byteLength} bytes exceeds field capacity of ${capacity} bytes at offset ${byteOffset}`);
+    }
+    lengthView[0] = bytes.byteLength;
+    new Uint8Array(ctx.buffer, byteOffset + 4, bytes.byteLength).set(bytes);
+  };
+  const readBytes = () => new Uint8Array(ctx.buffer, byteOffset + 4, lengthView[0]).slice();
+  return {
+    byteOffset,
+    byteLength: d.byteLength,
+    read: () => decoder.decode(readBytes()),
+    write: (v) => writeBytes(encoder.encode(d.schema ? d.schema.parse(v) : v))
+  };
+});
+function makeIO(ctx) {
+  const view = new DataView(ctx.buffer);
+  const byteView = new Uint8Array(ctx.buffer);
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const scalarIO = {
+    i8: { get: (o) => view.getInt8(o), set: (o, v) => view.setInt8(o, v) },
+    u8: { get: (o) => view.getUint8(o), set: (o, v) => view.setUint8(o, v) },
+    i16: { get: (o) => view.getInt16(o), set: (o, v) => view.setInt16(o, v) },
+    u16: { get: (o) => view.getUint16(o), set: (o, v) => view.setUint16(o, v) },
+    i32: { get: (o) => view.getInt32(o), set: (o, v) => view.setInt32(o, v) },
+    u32: { get: (o) => view.getUint32(o), set: (o, v) => view.setUint32(o, v) },
+    f32: { get: (o) => view.getFloat32(o), set: (o, v) => view.setFloat32(o, v) },
+    f64: { get: (o) => view.getFloat64(o), set: (o, v) => view.setFloat64(o, v) },
+    i64: { get: (o) => view.getBigInt64(o), set: (o, v) => view.setBigInt64(o, v) },
+    u64: { get: (o) => view.getBigUint64(o), set: (o, v) => view.setBigUint64(o, v) }
+  };
+  const readString = (offset, max) => {
+    const zero = byteView.indexOf(0, offset);
+    const len = zero === -1 || zero - offset >= max ? max : zero - offset;
+    return decoder.decode(byteView.slice(offset, offset + len));
+  };
+  let scratch = new Uint8Array(64);
+  const writeString = (offset, max, value) => {
+    if (scratch.length < max) scratch = new Uint8Array(max);
+    const { read, written } = encoder.encodeInto(value, scratch);
+    if (read < value.length || written > max) {
+      throw new Error(`String exceeds inline field capacity of ${max} bytes`);
+    }
+    byteView.set(scratch.subarray(0, written), offset);
+    if (written < max) byteView.fill(0, offset + written, offset + max);
+  };
+  const ops = (spec) => {
+    if (typeof spec === "string") {
+      const io = scalarIO[spec];
+      return { get: (o) => io.get(o), set: (o, v) => io.set(o, v) };
+    }
+    if ("bool" in spec) {
+      return { get: (o) => !!view.getUint8(o), set: (o, v) => view.setUint8(o, v ? 1 : 0) };
+    }
+    return { get: (o) => readString(o, spec.string), set: (o, v) => writeString(o, spec.string, v) };
+  };
+  const compile = (layout, offsets) => {
+    const readers = /* @__PURE__ */ new Map();
+    const writers = /* @__PURE__ */ new Map();
+    for (const key of Object.keys(layout)) {
+      const { get, set } = ops(layout[key]);
+      const rel = offsets[key];
+      readers.set(key, (base, out) => {
+        out[key] = get(base + rel);
+      });
+      writers.set(key, (base, record) => set(base + rel, record[key]));
+    }
+    const allReaders = [...readers.values()];
+    const allWriters = [...writers.values()];
+    return {
+      read(base, out = {}, fieldNames) {
+        if (fieldNames) {
+          for (const key of fieldNames) readers.get(key)(base, out);
+        } else {
+          for (const read of allReaders) read(base, out);
+        }
+        return out;
+      },
+      write(base, record, fieldNames) {
+        if (fieldNames) {
+          for (const key of fieldNames) writers.get(key)(base, record);
+        } else {
+          for (const write of allWriters) write(base, record);
+        }
+      }
+    };
+  };
+  return { ops, compile };
+}
+var structuredFactory = (d, ctx, byteOffset) => {
+  const { schema, byteLength, kind } = d;
+  const fixed = d;
+  if (fixed.layout && fixed.offsets && fixed.recordSize !== void 0) {
+    const flag = new Uint32Array(ctx.buffer, byteOffset, 2);
+    const base = byteOffset + 8;
+    const record = makeIO(ctx).compile(fixed.layout, fixed.offsets);
+    return {
+      byteOffset,
+      byteLength,
+      read: () => flag[0] ? record.read(base, {}) : void 0,
+      // unwritten on either thread
+      write: (v) => {
+        record.write(base, schema ? schema.parse(v) : v);
+        flag[0] = 1;
+      }
+    };
+  }
+  if (fixed.element !== void 0 && fixed.elementStride !== void 0 && fixed.capacity !== void 0) {
+    const flag = new Uint32Array(ctx.buffer, byteOffset, 1);
+    const count = new Uint32Array(ctx.buffer, byteOffset + 4, 1);
+    const el = makeIO(ctx).ops(fixed.element);
+    const stride = fixed.elementStride;
+    const capacity2 = fixed.capacity;
+    const base = byteOffset + 8;
+    return {
+      byteOffset,
+      byteLength,
+      read: () => {
+        if (!flag[0]) return void 0;
+        const n = count[0];
+        return Array.from({ length: n }, (_, i) => el.get(base + i * stride));
+      },
+      write: (v) => {
+        const parsed = schema ? schema.parse(v) : v;
+        if (parsed.length > capacity2) {
+          throw new Error(`${parsed.length} elements exceeds array capacity of ${capacity2}`);
+        }
+        parsed.forEach((v2, i) => el.set(base + i * stride, v2));
+        count[0] = parsed.length;
+        flag[0] = 1;
+      }
+    };
+  }
+  const capacity = byteLength - 4;
+  const lengthView = new Uint32Array(ctx.buffer, byteOffset, 1);
+  const writeBytes = (bytes) => {
+    if (bytes.byteLength > capacity) {
+      throw new Error(`Encoded value of ${bytes.byteLength} bytes exceeds field capacity of ${capacity} bytes at offset ${byteOffset}`);
+    }
+    lengthView[0] = bytes.byteLength;
+    new Uint8Array(ctx.buffer, byteOffset + 4, bytes.byteLength).set(bytes);
+  };
+  const readBytes = () => new Uint8Array(ctx.buffer, byteOffset + 4, lengthView[0]).slice();
+  return {
+    byteOffset,
+    byteLength,
+    read: () => {
+      const bytes = readBytes();
+      if (bytes.byteLength === 0) return void 0;
+      const value = ctx.codec.decode(bytes);
+      return schema ? schema.parse(value) : value;
+    },
+    write: (v) => writeBytes(ctx.codec.encode(schema ? schema.parse(v) : v))
+  };
+};
+registerConnectorFactory("object", structuredFactory);
+registerConnectorFactory("array", structuredFactory);
+function listFactory(d, ctx, byteOffset) {
+  const info = d;
+  const { offsets, recordSize, count } = info;
+  const record = makeIO(ctx).compile(info.layout, offsets);
+  const checkIndex = (index) => {
+    if (index < 0 || index >= count) {
+      throw new RangeError(`Record index ${index} out of bounds (0..${count - 1})`);
+    }
+  };
+  const readAt = (index, out = {}, fieldNames) => {
+    checkIndex(index);
+    return record.read(byteOffset + index * recordSize, out, fieldNames);
+  };
+  const writeAt = (index, rec, fieldNames) => {
+    checkIndex(index);
+    record.write(byteOffset + index * recordSize, rec, fieldNames);
+  };
+  const connector = {
+    byteOffset,
+    byteLength: d.byteLength,
+    recordCount: count,
+    recordSize,
+    readAt,
+    writeAt,
+    commit: () => {
+      if (ctx.version) {
+        Atomics.add(ctx.version.view, ctx.version.index, 1);
+        Atomics.notify(ctx.version.view, ctx.version.index);
+      }
+    },
+    read: () => Array.from({ length: count }, (_, i) => readAt(i)),
+    write: (records) => {
+      if (records.length > count) {
+        throw new Error(`${records.length} records exceeds list array capacity of ${count}`);
+      }
+      records.forEach((r, i) => writeAt(i, r));
+    }
+  };
+  return connector;
+}
+registerConnectorFactory("list", listFactory);
+var definedSharedMemories = [];
+function bindSharedMemories(buffer) {
+  for (const memory of definedSharedMemories) {
+    memory.bind(buffer);
+  }
+  memLog.info(`bound ${definedSharedMemories.length} contract(s) \u2014 ${fmtBytes(buffer.byteLength)} buffer`);
+}
+
+// ../../src/pool/memory.ts
+var MemoryManager = class {
+  memory;
+  maxPages;
+  constructor(config = {}) {
+    const initialPages = config.initialPages ?? 16;
+    this.maxPages = config.maximumPages ?? 16384;
+    this.memory = new WebAssembly.Memory({
+      initial: initialPages,
+      maximum: this.maxPages,
+      shared: true
+    });
+  }
+  /**
+   * Automatically checks if memory needs to grow to accommodate new bytes,
+   * and expands via memory.grow() if necessary. Thread-safe.
+   */
+  ensureCapacity(requiredBytes) {
+    const currentByteLength = this.memory.buffer.byteLength;
+    if (currentByteLength >= requiredBytes) return;
+    const bytesNeeded = requiredBytes - currentByteLength;
+    const pagesNeeded = Math.ceil(bytesNeeded / 65536);
+    const currentPages = this.memory.buffer.byteLength / 65536;
+    if (currentPages + pagesNeeded > this.maxPages) {
+      throw new Error(`Cannot grow memory: exceeds maximum page limit of ${this.maxPages}`);
+    }
+    this.memory.grow(pagesNeeded);
+  }
+  /**
+   * Creates a typed view over the shared memory buffer at a specific byte offset.
+   */
+  getView(type, byteOffset = 0, length) {
+    const buffer = this.memory.buffer;
+    switch (type) {
+      case "Int32":
+        return new Int32Array(buffer, byteOffset, length);
+      case "Float64":
+        return new Float64Array(buffer, byteOffset, length);
+      case "BigInt64":
+        return new BigInt64Array(buffer, byteOffset, length);
+      case "Uint8":
+        return new Uint8Array(buffer, byteOffset, length);
+      default:
+        throw new Error(`Unsupported view type: ${type}`);
+    }
+  }
+  /**
+   * Exposes the raw SharedArrayBuffer
+   */
+  getBuffer() {
+    return this.memory.buffer;
+  }
+};
+
+// ../../src/pool/errors.ts
+var PoolQueueFullError = class extends Error {
+  constructor(message = "WorkerPool task queue is full") {
+    super(message);
+    this.name = "PoolQueueFullError";
+  }
+};
+var TaskAbortedError = class extends Error {
+  constructor(message = "task aborted") {
+    super(message);
+    this.name = "AbortError";
+  }
+};
+var TaskTimeoutError = class extends Error {
+  constructor(message = "task timed out") {
+    super(message);
+    this.name = "TaskTimeoutError";
+  }
+};
+var WorkerCrashedError = class extends Error {
+  constructor(message = "worker crashed") {
+    super(message);
+    this.name = "WorkerCrashedError";
+  }
+};
+
+// ../../src/pool/workerPool.ts
+var poolLog = scoped("pool");
+var taskLog = scoped("task");
+var agg = () => ({
+  count: 0,
+  mean: 0,
+  max: 0,
+  add(v) {
+    this.count++;
+    this.mean += (v - this.mean) / this.count;
+    if (v > this.max) this.max = v;
+  }
+});
+var WorkerPoolImpl = class {
+  slots = [];
+  pending = /* @__PURE__ */ new Map();
+  nextMessageId = 0;
+  queue = [];
+  memoryManager;
+  workerUrl;
+  spawn;
+  concurrency;
+  maxQueue;
+  respawn;
+  taskTimeout;
+  closed = false;
+  drainWaiters = [];
+  statsAgg = {
+    completed: 0,
+    failed: 0,
+    /** aborts + timeouts. */
+    aborted: 0,
+    waitMs: agg(),
+    runMs: agg()
+  };
+  sharedMemory;
+  /** The attached memory-persistence adapter, if the config supplied one. */
+  persistence;
+  constructor(config) {
+    if (config.sharedMemory) {
+      if (typeof SharedArrayBuffer === "undefined" || typeof crossOriginIsolated !== "undefined" && !crossOriginIsolated) {
+        throw new Error(
+          "WorkerPool requires SharedArrayBuffer in a cross-origin isolated context \u2014 serve the page with COOP/COEP headers."
+        );
+      }
+    }
+    if (!config.workerUrl && !config.createWorker) {
+      throw new Error("WorkerPool requires either `workerUrl` or `createWorker` in its config.");
+    }
+    this.workerUrl = config.workerUrl;
+    this.spawn = config.createWorker ?? (() => new Worker(this.workerUrl, { type: "module" }));
+    this.concurrency = config.concurrency ?? 1;
+    this.maxQueue = config.maxQueue ?? Infinity;
+    this.respawn = config.respawn ?? true;
+    this.taskTimeout = config.taskTimeout;
+    if (config.sharedMemory) {
+      this.sharedMemory = config.sharedMemory;
+      this.memoryManager = new MemoryManager(config.memory);
+      this.memoryManager.ensureCapacity(this.sharedMemory.totalBytes);
+      this.sharedMemory.bind(this.memoryManager.getBuffer());
+      this.persistence = config.persistence?.(config.sharedMemory);
+    }
+    const requestedSize = config.poolSize ?? "auto";
+    const poolSize = requestedSize === "auto" ? navigator.hardwareConcurrency ?? 4 : requestedSize;
+    poolLog.info(
+      this.sharedMemory ? `spawning ${poolSize} worker(s) with ${fmtBytes(this.sharedMemory.totalBytes)} shared buffer` : `spawning ${poolSize} worker(s), message-only`,
+      { workerUrl: config.workerUrl ? String(config.workerUrl) : "createWorker()" }
+    );
+    poolLog.debug(`tip: setLogLevel('trace') for per-task detail`);
+    for (let i = 0; i < poolSize; i++) {
+      this.addWorker(this.spawn());
+    }
+    const tasks = config.tasks ?? {};
+    for (const [name, contract] of Object.entries(tasks)) {
+      if (name in this) {
+        poolLog.warn(`task "${name}" collides with a WorkerPool member \u2014 not installed`);
+        continue;
+      }
+      this[name] = (...args) => this.runTask(contract, ...args);
+    }
+    if (Object.keys(tasks).length > 0) {
+      poolLog.info(`task methods: ${Object.keys(tasks).join(", ")}`);
+    }
+  }
+  /** Adds a spawned worker: one message + one error listener, then the INIT handshake. */
+  addWorker(worker) {
+    const slot = { worker, inFlight: 0 };
+    worker.addEventListener("message", (event) => {
+      this.handleReply(slot, event.data);
+    });
+    worker.addEventListener("error", (event) => {
+      this.handleWorkerError(slot, event);
+    });
+    if (this.memoryManager) {
+      worker.postMessage({ type: "INIT_MEMORY", memory: this.memoryManager.memory });
+    } else {
+      worker.postMessage({ type: "INIT" });
+    }
+    this.slots.push(slot);
+    poolLog.debug(`worker spawned, ${this.memoryManager ? "INIT_MEMORY" : "INIT"} sent`);
+    return slot;
+  }
+  handleReply(slot, data) {
+    const entry = data.messageId !== void 0 ? this.pending.get(data.messageId) : void 0;
+    if (!entry) return;
+    this.pending.delete(data.messageId);
+    slot.inFlight--;
+    this.detach(entry);
+    if (!entry.done) {
+      entry.done = true;
+      this.statsAgg.runMs.add(performance.now() - (entry.sentAt ?? entry.enqueuedAt));
+      if (data.success) {
+        this.statsAgg.completed++;
+        taskLog.debug(`\u2190 ${entry.contract.taskId} ok`);
+        entry.resolve(data.result);
+      } else {
+        this.statsAgg.failed++;
+        taskLog.warn(`\u2190 ${entry.contract.taskId} failed: ${data.error}`);
+        entry.reject(new Error(data.error));
+      }
+    }
+    this.drainQueue();
+    this.checkDrained();
+  }
+  handleWorkerError(slot, event) {
+    if (this.closed) return;
+    const e = event;
+    const message = e?.message ?? (e?.error ? String(e.error) : "worker error");
+    poolLog.warn(`worker error: ${message}`);
+    for (const [id, entry] of [...this.pending]) {
+      if (entry.slot === slot) {
+        this.pending.delete(id);
+        this.detach(entry);
+        if (entry.done) continue;
+        entry.done = true;
+        this.statsAgg.failed++;
+        entry.reject(new WorkerCrashedError(message));
+      }
+    }
+    const idx = this.slots.indexOf(slot);
+    if (idx >= 0) this.slots.splice(idx, 1);
+    slot.worker.terminate();
+    if (this.respawn) {
+      poolLog.info("respawning crashed worker");
+      this.addWorker(this.spawn());
+    } else if (this.slots.length === 0) {
+      for (const entry of this.queue.splice(0)) {
+        entry.done = true;
+        this.detach(entry);
+        this.statsAgg.failed++;
+        entry.reject(new WorkerCrashedError(message));
+      }
+    }
+    this.drainQueue();
+    this.checkDrained();
+  }
+  /** Least-busy worker below its concurrency cap, if any. */
+  pickWorker() {
+    let best;
+    for (const slot of this.slots) {
+      if (slot.inFlight >= this.concurrency) continue;
+      if (!best || slot.inFlight < best.inFlight) best = slot;
+    }
+    return best;
+  }
+  drainQueue() {
+    let slot;
+    while (this.queue.length > 0 && (slot = this.pickWorker())) {
+      const entry = this.queue.shift();
+      if (entry.done) continue;
+      this.send(slot, entry);
+    }
+  }
+  send(slot, entry) {
+    const messageId = this.nextMessageId++;
+    entry.messageId = messageId;
+    entry.slot = slot;
+    entry.sentAt = performance.now();
+    this.statsAgg.waitMs.add(performance.now() - entry.enqueuedAt);
+    slot.inFlight++;
+    this.pending.set(messageId, entry);
+    taskLog.debug(`\u2192 ${entry.contract.taskId}`, { worker: this.slots.indexOf(slot), args: entry.args });
+    slot.worker.postMessage({
+      type: "EXECUTE_TASK",
+      messageId,
+      taskId: entry.contract.taskId,
+      args: entry.args
+    });
+  }
+  /** Detaches signal/timeout listeners from a finalized entry. */
+  detach(entry) {
+    if (entry.timer) clearTimeout(entry.timer);
+    if (entry.signal && entry.onSignalAbort) {
+      entry.signal.removeEventListener("abort", entry.onSignalAbort);
+    }
+  }
+  /**
+   * Abort/timeout path: a queued task is removed outright; an in-flight task
+   * stays in `pending` as an orphan — the worker is still running it, so the
+   * slot remains occupied until the reply arrives (handleReply frees it).
+   */
+  cancel(entry, err) {
+    if (entry.done) return;
+    const qi = this.queue.indexOf(entry);
+    if (qi >= 0) this.queue.splice(qi, 1);
+    entry.done = true;
+    this.detach(entry);
+    this.statsAgg.aborted++;
+    entry.reject(err);
+    this.drainQueue();
+    this.checkDrained();
+  }
+  checkDrained() {
+    if (this.queue.length === 0 && this.pending.size === 0) {
+      const waiters = this.drainWaiters.splice(0);
+      for (const w of waiters) w();
+    }
+  }
+  /**
+   * Full dispatch: least-busy scheduling, `concurrency` cap per worker,
+   * FIFO queue bounded by `maxQueue`, abort/timeout, and queue→reply timing.
+   */
+  dispatch(contract, args, options) {
+    if (this.closed || this.slots.length === 0) {
+      return Promise.reject(new WorkerCrashedError("WorkerPool has been terminated \u2014 no workers available."));
+    }
+    if (options?.signal?.aborted) {
+      return Promise.reject(new TaskAbortedError());
+    }
+    return new Promise((resolve, reject) => {
+      const entry = {
+        contract,
+        args,
+        enqueuedAt: performance.now(),
+        resolve,
+        reject,
+        done: false,
+        signal: options?.signal
+      };
+      if (options?.signal) {
+        entry.onSignalAbort = () => this.cancel(entry, new TaskAbortedError());
+        options.signal.addEventListener("abort", entry.onSignalAbort, { once: true });
+      }
+      const timeout = options?.timeout ?? this.taskTimeout;
+      if (timeout !== void 0) {
+        entry.timer = setTimeout(() => this.cancel(entry, new TaskTimeoutError()), timeout);
+      }
+      const slot = this.pickWorker();
+      if (slot) {
+        this.send(slot, entry);
+      } else if (this.queue.length >= this.maxQueue) {
+        entry.done = true;
+        this.detach(entry);
+        reject(new PoolQueueFullError());
+        return;
+      } else {
+        this.queue.push(entry);
+      }
+    });
+  }
+  /**
+   * Dispatches a task to the least-busy worker in the pool.
+   * The task contract guarantees the argument and result types across the thread boundary.
+   */
+  runTask(contract, ...args) {
+    return this.dispatch(contract, args);
+  }
+  /**
+   * The shared buffer handed to workers via INIT_MEMORY — undefined on
+   * message-only pools. Useful for passing the same buffer to auxiliaries
+   * (e.g. a second pool of HTTP workers via withSharedBuffer).
+   */
+  get sharedBuffer() {
+    return this.memoryManager?.getBuffer();
+  }
+  /**
+   * Live snapshot of the pool's worker slots — for auxiliary messaging that
+   * isn't task dispatch (e.g. routing accepted sockets into workers). The
+   * array is a copy; respawned workers appear on the next read. Do NOT use
+   * this to dispatch tasks — runTask/dispatch own the scheduling protocol.
+   */
+  get workers() {
+    return this.slots.map((s) => s.worker);
+  }
+  /** Running aggregates — no histograms, just counts and means. */
+  stats() {
+    return {
+      workers: this.slots.length,
+      idle: this.slots.filter((s) => s.inFlight === 0).length,
+      inFlight: this.pending.size,
+      queued: this.queue.length,
+      completed: this.statsAgg.completed,
+      failed: this.statsAgg.failed,
+      aborted: this.statsAgg.aborted,
+      waitMs: { count: this.statsAgg.waitMs.count, mean: this.statsAgg.waitMs.mean, max: this.statsAgg.waitMs.max },
+      runMs: { count: this.statsAgg.runMs.count, mean: this.statsAgg.runMs.mean, max: this.statsAgg.runMs.max }
+    };
+  }
+  /** Resolves once the queue is empty and nothing is in flight, then terminates. */
+  close() {
+    if (this.queue.length === 0 && this.pending.size === 0) {
+      this.terminate();
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.drainWaiters.push(() => {
+        this.terminate();
+        resolve();
+      });
+    });
+  }
+  terminate() {
+    this.closed = true;
+    void this.persistence?.stop()?.catch?.(
+      (e) => poolLog.warn("memory persistence stop failed", e)
+    );
+    poolLog.info(`terminating ${this.slots.length} worker(s)`);
+    const crashed = new WorkerCrashedError("pool terminated");
+    for (const [, entry] of this.pending) {
+      this.detach(entry);
+      if (entry.done) continue;
+      entry.done = true;
+      this.statsAgg.failed++;
+      entry.reject(crashed);
+    }
+    this.pending.clear();
+    for (const entry of this.queue.splice(0)) {
+      entry.done = true;
+      this.detach(entry);
+      this.statsAgg.failed++;
+      entry.reject(crashed);
+    }
+    for (const slot of this.slots) {
+      slot.worker.terminate();
+    }
+    this.slots = [];
+    this.checkDrained();
+  }
+};
+var WorkerPool = WorkerPoolImpl;
+
+export {
+  scoped,
+  bindSharedMemories,
+  WorkerPool
+};