@ricsam/r5d-worker 0.0.123 → 0.0.125

package/dist/mjs/recovery-journal.mjs

@@ -0,0 +1,687 @@
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+const WORKER_RECOVERY_JOURNAL_MAX_BATCH_ENTRIES = 256;
+const WORKER_RECOVERY_JOURNAL_MAX_PENDING_ENTRIES = 4096;
+const WORKER_RECOVERY_JOURNAL_MAX_PENDING_BYTES = 16 * 1024 * 1024;
+const WORKER_RECOVERY_JOURNAL_MAX_CONTROL_ENTRIES = 2048;
+const WORKER_RECOVERY_JOURNAL_MAX_CONTROL_BYTES = 1024 * 1024;
+const WORKER_RECOVERY_JOURNAL_MAX_ENTRY_BYTES = 8 * 1024 * 1024;
+const WORKER_RECOVERY_JOURNAL_OUTPUT_CHUNK_CHARACTERS = 64 * 1024;
+const WORKER_RECOVERY_JOURNAL_MAX_WAITING_ADMISSIONS = 512;
+const WORKER_RECOVERY_JOURNAL_MAX_WAITING_OUTPUT = 1024;
+const WORKER_RECOVERY_JOURNAL_MAX_WAITING_BYTES = 4 * 1024 * 1024;
+const WORKER_RECOVERY_JOURNAL_REPLAY_PAGE_FRAMES = 32;
+class WorkerRecoveryJournalError extends Error {
+  name = "WorkerRecoveryJournalError";
+}
+class WorkerRecoveryJournalBusyError extends WorkerRecoveryJournalError {
+  name = "WorkerRecoveryJournalBusyError";
+}
+class JournalBudget {
+  constructor(maxEntries, maxBytes) {
+    this.maxEntries = maxEntries;
+    this.maxBytes = maxBytes;
+  }
+  maxEntries;
+  maxBytes;
+  entries = 0;
+  bytes = 0;
+  fits(bytes) {
+    return this.entries + 1 <= this.maxEntries && this.bytes + bytes <= this.maxBytes;
+  }
+  reserve(bytes) {
+    if (!this.fits(bytes)) return false;
+    this.entries += 1;
+    this.bytes += bytes;
+    return true;
+  }
+  release(bytes) {
+    this.entries -= 1;
+    this.bytes -= bytes;
+  }
+}
+function approximateBytes(value) {
+  if (typeof value === "string") return value.length;
+  if (value && typeof value === "object") return JSON.stringify(value).length;
+  return 8;
+}
+function messageKeyed(message) {
+  return typeof message.requestId === "string" || typeof message.runId === "string" || typeof message.ptyId === "string";
+}
+function messageJournaled(message) {
+  return message.type === "exec_output" || message.type === "exec_exit" || message.type === "exec_error" || typeof message.requestId === "string";
+}
+function splitOutput(data, maxCharacters) {
+  if (data.length <= maxCharacters) return [data];
+  const chunks = [];
+  let start = 0;
+  while (start < data.length) {
+    let end = Math.min(data.length, start + maxCharacters);
+    const last = data.charCodeAt(end - 1);
+    if (end < data.length && last >= 55296 && last <= 56319) end -= 1;
+    chunks.push(data.slice(start, end));
+    start = end;
+  }
+  return chunks;
+}
+class WorkerRecoveryJournal {
+  ledgerId;
+  worker;
+  log;
+  maxBatchEntries;
+  maxEntryBytes;
+  maxWaitingAdmissions;
+  maxWaitingOutput;
+  maxWaitingBytes;
+  waitingBytes = 0;
+  retainedReplyBytes = 0;
+  general;
+  control;
+  nextSeq = 1;
+  committedSeq = 0;
+  pending = [];
+  inFlight = null;
+  nextBatchId = 1;
+  waiters = [];
+  outbound = [];
+  deliveryPaused = 0;
+  replayCoveredSeq = 0;
+  failure = null;
+  closed = false;
+  pendingAdmissions = /* @__PURE__ */ new Map();
+  activeOperations = /* @__PURE__ */ new Map();
+  cancelledRequestIds = /* @__PURE__ */ new Set();
+  unknownRequestIds = /* @__PURE__ */ new Set();
+  unknownRunIds = /* @__PURE__ */ new Set();
+  coalescedControl = /* @__PURE__ */ new Map();
+  flushWaiters = [];
+  /** Delivers one committed message in order; returns false when the transport declined it (the pumps re-send). */
+  deliver;
+  /** Invoked once when the journal fails closed. */
+  onFailure;
+  constructor(worker, ledgerId, options) {
+    this.worker = worker;
+    this.ledgerId = ledgerId;
+    this.log = options.log ?? ((line) => process.stderr.write(`${line}
+`));
+    this.maxBatchEntries = options.maxBatchEntries ?? WORKER_RECOVERY_JOURNAL_MAX_BATCH_ENTRIES;
+    this.maxEntryBytes = options.maxEntryBytes ?? WORKER_RECOVERY_JOURNAL_MAX_ENTRY_BYTES;
+    this.maxWaitingAdmissions = options.maxWaitingAdmissions ?? WORKER_RECOVERY_JOURNAL_MAX_WAITING_ADMISSIONS;
+    this.maxWaitingOutput = options.maxWaitingOutput ?? WORKER_RECOVERY_JOURNAL_MAX_WAITING_OUTPUT;
+    this.maxWaitingBytes = options.maxWaitingBytes ?? WORKER_RECOVERY_JOURNAL_MAX_WAITING_BYTES;
+    this.general = new JournalBudget(
+      options.maxPendingEntries ?? WORKER_RECOVERY_JOURNAL_MAX_PENDING_ENTRIES,
+      options.maxPendingBytes ?? WORKER_RECOVERY_JOURNAL_MAX_PENDING_BYTES
+    );
+    this.control = new JournalBudget(
+      options.maxControlEntries ?? WORKER_RECOVERY_JOURNAL_MAX_CONTROL_ENTRIES,
+      options.maxControlBytes ?? WORKER_RECOVERY_JOURNAL_MAX_CONTROL_BYTES
+    );
+    worker.on("message", (reply) => this.onReply(reply));
+    worker.on(
+      "error",
+      (error) => this.fail(new WorkerRecoveryJournalError(`Recovery journal thread error: ${error.message}`, { cause: error }))
+    );
+    worker.on("exit", (code) => {
+      if (!this.closed) this.fail(new WorkerRecoveryJournalError(`Recovery journal thread exited with code ${code}`));
+    });
+    worker.unref();
+  }
+  /** Start the journal thread, open the store there (its crash recovery runs there) and return once it is ready. */
+  static open(options) {
+    const threadModulePath = options.threadModulePath ?? workerRecoveryJournalThreadModulePath();
+    return new Promise((resolve, reject) => {
+      const worker = new Worker(threadModulePath, { workerData: { ...options.threadWorkerData, filename: options.filename } });
+      let settled = false;
+      const onReady = (reply) => {
+        if (settled || !reply || reply.type !== "ready") return;
+        settled = true;
+        worker.off("message", onReady);
+        worker.off("error", onError);
+        worker.off("exit", onExit);
+        resolve(new WorkerRecoveryJournal(worker, reply.ledgerId, options));
+      };
+      const onError = (error) => {
+        if (settled) return;
+        settled = true;
+        reject(new WorkerRecoveryJournalError(`Recovery journal could not open ${options.filename}: ${error.message}`, { cause: error }));
+      };
+      const onExit = (code) => {
+        if (settled) return;
+        settled = true;
+        reject(new WorkerRecoveryJournalError(`Recovery journal thread exited with code ${code} before it was ready`));
+      };
+      worker.on("message", onReady);
+      worker.on("error", onError);
+      worker.on("exit", onExit);
+    });
+  }
+  status() {
+    return {
+      pendingEntries: this.pending.length + (this.inFlight?.entries.length ?? 0),
+      retainedEntries: this.general.entries,
+      retainedBytes: this.general.bytes,
+      controlEntries: this.control.entries,
+      controlBytes: this.control.bytes,
+      waitingAdmissions: this.waiters.filter((waiter) => waiter.kind === "admit").length,
+      waitingOutput: this.waiters.filter((waiter) => waiter.kind === "output").length,
+      waitingBytes: this.waitingBytes,
+      retainedReplyBytes: this.retainedReplyBytes,
+      committedSeq: this.committedSeq,
+      appendedSeq: this.nextSeq - 1,
+      undelivered: this.outbound.length,
+      failed: this.failure?.message ?? null
+    };
+  }
+  /**
+   * Durably admit an inbound operation; resolves after the commit. Waits for
+   * general budget in a bounded waiting room; when that room is full the
+   * admission is refused at once (WorkerRecoveryJournalBusyError) so the
+   * message is neither acknowledged nor retained.
+   */
+  async admit(message) {
+    this.assertOpen();
+    const tracked = {
+      requestId: message.requestId,
+      sessionId: typeof message.sessionId === "string" ? message.sessionId : void 0,
+      runId: typeof message.runId === "string" ? message.runId : void 0,
+      requestType: message.type,
+      state: "accepted"
+    };
+    this.pendingAdmissions.set(message.requestId, tracked);
+    try {
+      const bytes = approximateBytes(message);
+      if (bytes > this.maxEntryBytes) {
+        throw new WorkerRecoveryJournalBusyError(
+          `Recovery journal refuses a ${bytes}-byte request; the entry bound is ${this.maxEntryBytes} bytes`
+        );
+      }
+      await this.reserveGeneral(bytes, "admit");
+      const result = await this.append("admit", [message], bytes, this.general, null);
+      if (result.cancelled) this.cancelledRequestIds.add(message.requestId);
+      if (result.admission === "new") this.activeOperations.set(message.requestId, tracked);
+      return result;
+    } finally {
+      this.pendingAdmissions.delete(message.requestId);
+    }
+  }
+  /**
+   * Re-admit an unknown branch deletion. Like `admit`, the request is a
+   * pending admission from before the await, so a session cancellation that
+   * lands while the disk is slow snapshots it and the handler's recheck after
+   * the await refuses to rerun the deletion.
+   */
+  async readmitUnknownBranchDeletion(requestId, sessionId) {
+    this.assertOpen();
+    const tracked = { requestId, sessionId, runId: void 0, requestType: "delete_project_branch", state: "accepted" };
+    this.pendingAdmissions.set(requestId, tracked);
+    try {
+      const readmitted = await this.appendControlOrThrow("readmitUnknownBranchDeletion", [requestId]);
+      if (readmitted && this.pendingAdmissions.get(requestId) === tracked) {
+        this.activeOperations.set(requestId, tracked);
+        if (!this.cancelledRequestIds.has(requestId)) this.unknownRequestIds.delete(requestId);
+      }
+      return readmitted;
+    } finally {
+      if (this.pendingAdmissions.get(requestId) === tracked) this.pendingAdmissions.delete(requestId);
+    }
+  }
+  /**
+   * Queue an outbound message. Keyed messages are recorded (when the store
+   * records their type) and delivered in order after their commit; other
+   * messages are delivered at once. Returns false when the message was not
+   * queued: its operation is already unknown, or the budget cannot hold it,
+   * in which case the operation is marked unknown so it is neither
+   * acknowledged early nor sent later.
+   */
+  send(message) {
+    if (this.failure || this.closed) return false;
+    if (!messageKeyed(message)) {
+      this.deliver?.(message);
+      return true;
+    }
+    const requestId = typeof message.requestId === "string" ? message.requestId : void 0;
+    const runId = typeof message.runId === "string" ? message.runId : void 0;
+    if (requestId && this.unknownRequestIds.has(requestId) || runId && this.unknownRunIds.has(runId)) return false;
+    const bytes = approximateBytes(message);
+    const journaled = messageJournaled(message);
+    if (journaled && bytes > this.maxEntryBytes) {
+      this.refuse(message, `is ${bytes} bytes, above the ${this.maxEntryBytes}-byte entry bound`);
+      return false;
+    }
+    if (!this.general.reserve(bytes)) {
+      if (journaled) {
+        this.refuse(message, `does not fit the journal budget (${this.general.entries} entries, ${this.general.bytes} bytes retained)`);
+      } else {
+        this.log(
+          `[r5d-worker] recovery journal budget is full; dropping ${message.type} for ${runId ?? requestId ?? String(message.ptyId)}`
+        );
+      }
+      return false;
+    }
+    const entry = { seq: this.nextSeq, journaled, message, bytes, requestId, runId, recorded: null, dropped: false };
+    if (!journaled) {
+      this.outbound.push(entry);
+      this.deliverReady();
+      return true;
+    }
+    this.enqueueRecord(entry);
+    return true;
+  }
+  /**
+   * Queue an output frame, split into bounded records, waiting for budget so
+   * a stalled journal throttles the producer (and through the pipe, the
+   * child) instead of growing memory.
+   */
+  async sendOutput(frame) {
+    if (this.failure || this.closed) return;
+    if (this.unknownRunIds.has(frame.runId)) return;
+    for (const data of splitOutput(frame.data, WORKER_RECOVERY_JOURNAL_OUTPUT_CHUNK_CHARACTERS)) {
+      const chunk = { ...frame, data };
+      const bytes = approximateBytes(chunk);
+      if (bytes > this.general.maxBytes) {
+        this.refuse(chunk, `is ${bytes} bytes, above the ${this.general.maxBytes}-byte journal budget`);
+        return;
+      }
+      await this.reserveGeneral(bytes, "output");
+      if (this.failure || this.closed) {
+        this.general.release(bytes);
+        return;
+      }
+      this.enqueueRecord({
+        seq: this.nextSeq,
+        journaled: true,
+        message: chunk,
+        bytes,
+        requestId: void 0,
+        runId: frame.runId,
+        recorded: null,
+        dropped: false
+      });
+    }
+  }
+  /**
+   * Reserve general budget atomically, waiting in the bounded room of `kind`
+   * when it does not fit now. The waiting room is bounded in count and in
+   * payload bytes (the message a waiting admission holds is charged before it
+   * waits), and an entry that could never fit the general budget is refused
+   * at once rather than parked at the head of the queue.
+   */
+  reserveGeneral(bytes, kind) {
+    if (this.failure) return Promise.reject(this.failure);
+    if (bytes > this.general.maxBytes) {
+      return Promise.reject(
+        new WorkerRecoveryJournalBusyError(`Recovery journal refuses a ${bytes}-byte entry; the budget is ${this.general.maxBytes} bytes`)
+      );
+    }
+    if (this.waiters.length === 0 && this.general.reserve(bytes)) return Promise.resolve();
+    const waiting = this.waiters.filter((waiter) => waiter.kind === kind).length;
+    const room = kind === "admit" ? this.maxWaitingAdmissions : this.maxWaitingOutput;
+    const overflow = waiting >= room ? `${waiting} ${kind === "admit" ? "admissions" : "output producers"} waiting` : this.waitingBytes + bytes > this.maxWaitingBytes ? `${this.waitingBytes} bytes waiting` : null;
+    if (overflow) {
+      if (kind === "output") {
+        this.fail(new WorkerRecoveryJournalError(`Recovery journal has ${overflow}; refusing to buffer more output`));
+        return Promise.reject(this.failure);
+      }
+      return Promise.reject(
+        new WorkerRecoveryJournalBusyError(`Recovery journal has ${overflow} for the disk; refusing another admission`)
+      );
+    }
+    this.waitingBytes += bytes;
+    return new Promise((resolve, reject) => this.waiters.push({ bytes, kind, resolve, reject }));
+  }
+  /** Reserve for the head waiter inside this synchronous call, so no continuation can outrun the accounting. */
+  wakeWaiters() {
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters[0];
+      if (!this.general.reserve(waiter.bytes)) return;
+      this.waiters.shift();
+      this.waitingBytes -= waiter.bytes;
+      waiter.resolve();
+    }
+  }
+  enqueueRecord(entry) {
+    const promise = this.append("record", [entry.message], entry.bytes, this.general, entry, (seq) => {
+      entry.seq = seq;
+      this.outbound.push(entry);
+    });
+    promise.then(
+      (result) => {
+        if (entry.dropped) {
+          this.releaseOutbound(entry);
+          this.wakeWaiters();
+          return;
+        }
+        entry.recorded = { suppressed: result.suppressed, message: result.recorded };
+        this.trackRecorded(result.recorded, result.suppressed);
+        this.deliverReady();
+      },
+      () => {
+      }
+    );
+  }
+  refuse(message, reason) {
+    const requestId = typeof message.requestId === "string" ? message.requestId : void 0;
+    const runId = typeof message.runId === "string" ? message.runId : void 0;
+    this.log(
+      `[r5d-worker] recovery journal: ${message.type}${requestId ? ` ${requestId}` : ""}${runId ? ` run ${runId}` : ""} ${reason}; it is not sent and its operation becomes unknown`
+    );
+    if (requestId) this.unknown(requestId);
+    else if (runId) this.unknownRun(runId);
+  }
+  trackRecorded(message, suppressed) {
+    if (suppressed) return;
+    if ((message.type === "exec_exit" || message.type === "exec_error") && typeof message.runId === "string") {
+      for (const [requestId, operation2] of this.activeOperations) {
+        if (operation2.runId === message.runId && operation2.requestType === "exec_start") this.activeOperations.delete(requestId);
+      }
+      return;
+    }
+    if (typeof message.requestId !== "string") return;
+    const operation = this.activeOperations.get(message.requestId);
+    if (!operation) return;
+    if (message.type === "exec_accepted" || message.type === "operation_queued") operation.state = "preparing";
+    else if (message.type === "exec_started") operation.state = "running";
+    else if (message.type !== "operation_received") this.activeOperations.delete(message.requestId);
+  }
+  /**
+   * Mark an operation unknown: never sent again (undelivered messages for it
+   * are dropped now, and the durable mark keeps replay from resurrecting it).
+   * Coalesced per id; uses the reserved control budget.
+   */
+  unknown(requestId) {
+    this.unknownRequestIds.add(requestId);
+    const operation = this.activeOperations.get(requestId) ?? this.pendingAdmissions.get(requestId);
+    const runId = operation?.requestType === "exec_start" || operation?.requestType === "exec" ? operation.runId : void 0;
+    if (runId) this.unknownRunIds.add(runId);
+    this.activeOperations.delete(requestId);
+    this.pendingAdmissions.delete(requestId);
+    this.dropOutbound((entry) => entry.requestId === requestId || runId !== void 0 && entry.runId === runId);
+    this.appendControl(`unknown:${requestId}`, "unknown", [requestId]);
+  }
+  unknownRun(runId) {
+    this.unknownRunIds.add(runId);
+    for (const [requestId, operation] of this.activeOperations) if (operation.runId === runId) this.activeOperations.delete(requestId);
+    this.dropOutbound((entry) => entry.runId === runId);
+    this.appendControl(`unknownRun:${runId}`, "unknownRun", [runId]);
+  }
+  acknowledgeResult(requestId) {
+    this.appendControl(`acknowledgeResult:${requestId}`, "acknowledgeResult", [requestId]);
+  }
+  /** Monotonic per stream: a later acknowledgement replaces a pending earlier one. */
+  acknowledgeOutput(runId, stream, offset) {
+    this.appendControl(`acknowledgeOutput:${runId}:${stream}`, "acknowledgeOutput", [runId, stream, offset]);
+  }
+  acknowledgeTerminal(runId) {
+    this.appendControl(`acknowledgeTerminal:${runId}`, "acknowledgeTerminal", [runId]);
+  }
+  /**
+   * Snapshot every admitted and pending operation of the session as cancelled
+   * (the handlers check `isRequestCancelled` at their fences) and append the
+   * durable cancellation, which the thread applies after every admission
+   * appended before it. Resolves after the commit.
+   */
+  cancelSession(sessionId) {
+    for (const operation of [...this.pendingAdmissions.values(), ...this.activeOperations.values()]) {
+      if (operation.sessionId === sessionId) this.cancelledRequestIds.add(operation.requestId);
+    }
+    return this.appendControlOrThrow("cancelSession", [sessionId]).then(() => void 0);
+  }
+  isRequestCancelled(requestId) {
+    return this.cancelledRequestIds.has(requestId);
+  }
+  /** Every operation admitted or awaiting admission in this process that has not completed, for the runtime fence and lease expiry. */
+  activeAndPendingOperations() {
+    return [...this.pendingAdmissions.values(), ...this.activeOperations.values()].map((operation) => ({
+      requestId: operation.requestId,
+      requestType: operation.requestType,
+      state: operation.state,
+      ...operation.runId ? { runId: operation.runId } : {},
+      ...operation.sessionId ? { sessionId: operation.sessionId } : {}
+    }));
+  }
+  /**
+   * The handshake read. One entry, so it sees exactly the entries appended
+   * before it and none after: the replay boundary. Callers pause delivery
+   * before appending it and resume after the handshake, so every keyed
+   * message committed before the mark is replayed once (from the store) and
+   * nothing committed after it can enter the replay of responses, operations
+   * or terminals; output pages that follow may re-send frames the pump would
+   * re-send anyway, which the server's offset cursors absorb.
+   */
+  async recoveryState(requests) {
+    this.assertOpen();
+    this.replayCoveredSeq = this.nextSeq - 1;
+    this.dropOutbound((entry) => entry.journaled && entry.seq <= this.replayCoveredSeq && entry.recorded !== null);
+    const state = await this.appendControlOrThrow("recoveryState", [requests]);
+    this.retainedReplyBytes += approximateBytes(state);
+    this.retainedStateBytes += approximateBytes(state);
+    return state;
+  }
+  retainedStateBytes = 0;
+  /** Output replay, one bounded page at a time; a page is accounted until the consumer asks for the next one. */
+  async *outputReplay(offsets, pageFrames = WORKER_RECOVERY_JOURNAL_REPLAY_PAGE_FRAMES) {
+    this.assertOpen();
+    const replayId = await this.appendControlOrThrow("outputReplayBegin", [offsets ?? []]);
+    let retainedPageBytes = 0;
+    try {
+      while (true) {
+        const page = await this.appendControlOrThrow("outputReplayNext", [replayId, pageFrames]);
+        retainedPageBytes = approximateBytes(page.frames);
+        this.retainedReplyBytes += retainedPageBytes;
+        if (page.frames.length > 0) yield page.frames;
+        this.retainedReplyBytes -= retainedPageBytes;
+        retainedPageBytes = 0;
+        if (page.done) return;
+      }
+    } finally {
+      this.retainedReplyBytes -= retainedPageBytes;
+      if (!this.failure && !this.closed) void this.appendControlOrThrow("outputReplayEnd", [replayId]).catch(() => void 0);
+    }
+  }
+  terminals() {
+    this.assertOpen();
+    return this.appendControlOrThrow("terminals", []);
+  }
+  /** Delivery of committed keyed messages is held (in order) while a handshake replays from the store. */
+  pauseDelivery() {
+    this.deliveryPaused += 1;
+  }
+  resumeDelivery() {
+    this.deliveryPaused = Math.max(0, this.deliveryPaused - 1);
+    if (this.deliveryPaused === 0) {
+      this.retainedReplyBytes -= this.retainedStateBytes;
+      this.retainedStateBytes = 0;
+    }
+    this.deliverReady();
+  }
+  /** Resolves once every entry appended so far is committed (or the journal failed). */
+  flush() {
+    if (this.failure) return Promise.resolve();
+    const target = this.nextSeq - 1;
+    if (this.committedSeq >= target) return Promise.resolve();
+    return new Promise((resolve) => this.flushWaiters.push({ target, resolve }));
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.failEntries(new WorkerRecoveryJournalError("Recovery journal is closed"));
+    void this.worker.terminate();
+  }
+  assertOpen() {
+    if (this.failure) throw new WorkerRecoveryJournalError(`${this.failure.message}; the worker runtime must restart`);
+    if (this.closed) throw new WorkerRecoveryJournalError("Recovery journal is closed");
+  }
+  /** Control entries are tiny and idempotent per key: a pending one is updated in place instead of queued again. */
+  appendControl(key, op, args) {
+    if (this.failure || this.closed) return;
+    const existing = this.coalescedControl.get(key);
+    if (existing && !existing.dispatched) {
+      this.control.release(existing.bytes);
+      existing.args = args;
+      existing.bytes = approximateBytes(args);
+      this.control.entries += 1;
+      this.control.bytes += existing.bytes;
+      return;
+    }
+    const bytes = approximateBytes(args);
+    if (!this.control.reserve(bytes)) {
+      this.fail(
+        new WorkerRecoveryJournalError(
+          `Recovery journal control budget is exhausted (${this.control.entries} entries); cannot record ${op}`
+        )
+      );
+      return;
+    }
+    const appended = this.append(op, args, bytes, this.control, null);
+    appended.catch(() => void 0);
+    this.coalescedControl.set(key, this.lastAppended);
+  }
+  /** A control-budget entry whose result the caller awaits; rejects when the budget is exhausted. */
+  appendControlOrThrow(op, args) {
+    if (this.failure) return Promise.reject(this.failure);
+    if (this.closed) return Promise.reject(new WorkerRecoveryJournalError("Recovery journal is closed"));
+    const bytes = approximateBytes(args);
+    if (!this.control.reserve(bytes)) {
+      return Promise.reject(
+        new WorkerRecoveryJournalBusyError(
+          `Recovery journal control budget is exhausted (${this.control.entries} entries); cannot run ${op}`
+        )
+      );
+    }
+    return this.append(op, args, bytes, this.control, null);
+  }
+  lastAppended = null;
+  /** Queue an entry whose budget was already reserved from `budget`. */
+  append(op, args, bytes, budget, outbound, onSeq) {
+    if (this.failure || this.closed) {
+      budget.release(bytes);
+      return Promise.reject(this.failure ?? new WorkerRecoveryJournalError("Recovery journal is closed"));
+    }
+    const promise = new Promise((resolve, reject) => {
+      const seq = this.nextSeq++;
+      const entry = { seq, op, args, bytes, budget, outbound, dispatched: false, resolve, reject };
+      this.pending.push(entry);
+      this.lastAppended = entry;
+      onSeq?.(seq);
+    });
+    this.dispatch();
+    return promise;
+  }
+  dispatch() {
+    if (this.inFlight || this.pending.length === 0 || this.failure || this.closed) return;
+    const entries = this.pending.splice(0, this.maxBatchEntries);
+    for (const entry of entries) entry.dispatched = true;
+    const id = this.nextBatchId++;
+    this.inFlight = { id, entries };
+    this.worker.ref();
+    const request = {
+      type: "batch",
+      id,
+      entries: entries.map((entry) => ({ seq: entry.seq, op: entry.op, args: entry.args }))
+    };
+    try {
+      this.worker.postMessage(request);
+    } catch (error) {
+      this.fail(
+        new WorkerRecoveryJournalError(
+          `Recovery journal batch could not be sent: ${error instanceof Error ? error.message : String(error)}`
+        )
+      );
+    }
+  }
+  onReply(reply) {
+    if (!reply || typeof reply !== "object" || reply.type === "ready") return;
+    const inFlight = this.inFlight;
+    if (!inFlight || inFlight.id !== reply.id) return;
+    if (reply.type === "batch_failure") {
+      this.fail(new WorkerRecoveryJournalError(`Recovery journal commit failed: ${reply.error.message}`));
+      return;
+    }
+    this.inFlight = null;
+    const values = new Map(reply.results.map((result) => [result.seq, result.value]));
+    for (const entry of inFlight.entries) {
+      this.committedSeq = Math.max(this.committedSeq, entry.seq);
+      if (!entry.outbound) entry.budget.release(entry.bytes);
+      entry.resolve(values.get(entry.seq));
+    }
+    for (const [key, entry] of [...this.coalescedControl]) {
+      if (entry.dispatched) this.coalescedControl.delete(key);
+    }
+    for (const waiter of this.flushWaiters.splice(0)) {
+      if (waiter.target <= this.committedSeq) waiter.resolve();
+      else this.flushWaiters.push(waiter);
+    }
+    this.wakeWaiters();
+    if (this.pending.length === 0) this.worker.unref();
+    this.dispatch();
+  }
+  dropOutbound(predicate) {
+    for (let index = this.outbound.length - 1; index >= 0; index -= 1) {
+      const entry = this.outbound[index];
+      if (!predicate(entry)) continue;
+      this.outbound.splice(index, 1);
+      if (entry.journaled && !entry.recorded) entry.dropped = true;
+      else this.releaseOutbound(entry);
+    }
+    this.wakeWaiters();
+  }
+  releaseOutbound(entry) {
+    this.general.release(entry.bytes);
+  }
+  deliverReady() {
+    if (this.deliveryPaused > 0) return;
+    while (this.outbound.length > 0) {
+      const head = this.outbound[0];
+      if (head.journaled && !head.recorded) return;
+      this.outbound.shift();
+      const suppressed = head.recorded?.suppressed === true || head.journaled && head.seq <= this.replayCoveredSeq || head.requestId !== void 0 && this.unknownRequestIds.has(head.requestId) || head.runId !== void 0 && this.unknownRunIds.has(head.runId);
+      if (!suppressed) this.deliver?.(head.recorded ? head.recorded.message : head.message);
+      this.releaseOutbound(head);
+    }
+    this.wakeWaiters();
+  }
+  fail(error) {
+    if (this.failure || this.closed) return;
+    this.failure = error;
+    this.log(`[r5d-worker] ${error.message}`);
+    this.failEntries(error);
+    this.onFailure?.(error);
+  }
+  failEntries(error) {
+    const inFlight = this.inFlight;
+    this.inFlight = null;
+    for (const entry of [...inFlight?.entries ?? [], ...this.pending.splice(0)]) entry.reject(error);
+    for (const waiter of this.waiters.splice(0)) waiter.reject(error);
+    this.waitingBytes = 0;
+    this.retainedReplyBytes = 0;
+    this.retainedStateBytes = 0;
+    for (const waiter of this.flushWaiters.splice(0)) waiter.resolve();
+    this.outbound.splice(0);
+    this.coalescedControl.clear();
+    this.general.entries = 0;
+    this.general.bytes = 0;
+    this.control.entries = 0;
+    this.control.bytes = 0;
+  }
+}
+function workerRecoveryJournalThreadModulePath() {
+  return path.join(path.dirname(__filename), `recovery-journal-thread${path.extname(__filename)}`);
+}
+export {
+  WORKER_RECOVERY_JOURNAL_MAX_BATCH_ENTRIES,
+  WORKER_RECOVERY_JOURNAL_MAX_CONTROL_BYTES,
+  WORKER_RECOVERY_JOURNAL_MAX_CONTROL_ENTRIES,
+  WORKER_RECOVERY_JOURNAL_MAX_ENTRY_BYTES,
+  WORKER_RECOVERY_JOURNAL_MAX_PENDING_BYTES,
+  WORKER_RECOVERY_JOURNAL_MAX_PENDING_ENTRIES,
+  WORKER_RECOVERY_JOURNAL_MAX_WAITING_ADMISSIONS,
+  WORKER_RECOVERY_JOURNAL_MAX_WAITING_BYTES,
+  WORKER_RECOVERY_JOURNAL_MAX_WAITING_OUTPUT,
+  WORKER_RECOVERY_JOURNAL_OUTPUT_CHUNK_CHARACTERS,
+  WORKER_RECOVERY_JOURNAL_REPLAY_PAGE_FRAMES,
+  WorkerRecoveryJournal,
+  WorkerRecoveryJournalBusyError,
+  WorkerRecoveryJournalError,
+  workerRecoveryJournalThreadModulePath
+};