@ng-doc/builder 22.0.0-beta.1 → 22.0.0

package/generator/worker/index.js

@@ -0,0 +1,1030 @@
+// libs/builder/generator/worker/index.ts
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// libs/builder/generator/worker/protocol.ts
+function encode(value) {
+  const result = JSON.stringify(
+    value,
+    function(key, item) {
+      const original = this[key];
+      if (typeof item === "function" || typeof item === "symbol" || typeof item === "bigint" || typeof item === "number" && !Number.isFinite(item) || original !== null && typeof original === "object" && !Array.isArray(original) && (Object.getPrototypeOf(original) !== Object.prototype && Object.getPrototypeOf(original) !== null || typeof original.toJSON === "function"))
+        throw new Error("Worker transport requires JSON values");
+      return item;
+    }
+  );
+  if (result === void 0) throw new Error("Worker transport requires a JSON value");
+  return result;
+}
+function decode(value) {
+  if (typeof value !== "string") throw new Error("Worker message must be JSON text");
+  const parsed = JSON.parse(value);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Worker message must be an object");
+  }
+  return parsed;
+}
+function resultFrom(value) {
+  if (value === null || typeof value !== "object") throw new Error("Invalid compilation result");
+  const result = value;
+  if (!Array.isArray(result.dependencies) || !Array.isArray(result.diagnostics) || !Array.isArray(result.whyRebuilt) || result.candidate !== void 0 && (result.candidate === null || typeof result.candidate !== "object" || !Array.isArray(result.candidate.artifacts))) {
+    throw new Error("Invalid compilation result");
+  }
+  return result;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function object(value, what) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`Invalid snapshot delta: ${what}`);
+  return value;
+}
+function strings(value, what) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+    throw new Error(`Invalid snapshot delta: ${what}`);
+  return value;
+}
+function assemble(keys, set, base, what, artifacts) {
+  const result = {};
+  for (const key of keys) {
+    if (key === "__proto__" || Object.hasOwn(result, key))
+      throw new Error(`Invalid snapshot delta: ${what} key ${key}`);
+    if (artifacts && key === "artifacts") result[key] = artifacts;
+    else if (Object.hasOwn(set, key)) result[key] = set[key];
+    else if (base && Object.hasOwn(base, key)) result[key] = base[key];
+    else throw new Error(`Invalid snapshot delta: ${what} has no base value for ${key}`);
+  }
+  return result;
+}
+function applySnapshotDelta(base, value) {
+  const delta = object(value, "delta");
+  if (delta["base"] !== (base?.revision ?? null))
+    throw new Error(
+      `Invalid snapshot delta: base ${String(delta["base"])} is not ${String(base?.revision ?? null)}`
+    );
+  const previous = /* @__PURE__ */ new Map();
+  for (const artifact of base?.artifacts ?? []) {
+    if (previous.has(artifact.id))
+      throw new Error(`Invalid snapshot delta: duplicate base artifact ${artifact.id}`);
+    previous.set(artifact.id, artifact);
+  }
+  if (!Array.isArray(delta["artifacts"])) throw new Error("Invalid snapshot delta: artifacts");
+  const seen = /* @__PURE__ */ new Set();
+  const artifacts = delta["artifacts"].map((item) => {
+    const entry = object(item, "artifact entry");
+    const id = entry["id"];
+    const revision = entry["revision"];
+    if (typeof id !== "string" || typeof revision !== "string" || seen.has(id))
+      throw new Error(`Invalid snapshot delta: artifact ${String(id)}`);
+    seen.add(id);
+    const old = previous.get(id);
+    if (!("keys" in entry)) {
+      if (!old || old.revision !== revision)
+        throw new Error(`Invalid snapshot delta: no base artifact ${id} at ${revision}`);
+      return old;
+    }
+    const artifact = assemble(
+      strings(entry["keys"], `artifact ${id} keys`),
+      object(entry["set"], `artifact ${id} values`),
+      old,
+      `artifact ${id}`
+    );
+    if (artifact["id"] !== id || artifact["revision"] !== revision)
+      throw new Error(`Invalid snapshot delta: artifact ${id} identity`);
+    return artifact;
+  });
+  const keys = strings(delta["keys"], "snapshot keys");
+  if (!keys.includes("artifacts")) throw new Error("Invalid snapshot delta: snapshot artifacts");
+  const snapshot = assemble(
+    keys,
+    object(delta["set"], "snapshot values"),
+    base,
+    "snapshot",
+    artifacts
+  );
+  if (typeof snapshot["revision"] !== "string" || typeof snapshot["projectId"] !== "string")
+    throw new Error("Invalid snapshot delta: snapshot identity");
+  return snapshot;
+}
+function deepFreeze(value) {
+  const pending = [value];
+  while (pending.length) {
+    const item = pending.pop();
+    if (item === null || typeof item !== "object" || Object.isFrozen(item)) continue;
+    Object.freeze(item);
+    for (const child of Object.values(item)) pending.push(child);
+  }
+  return value;
+}
+var PROGRESS_PHASES = /* @__PURE__ */ new Set([
+  "boot",
+  "discovery",
+  "restore",
+  "semantic",
+  "plan",
+  "describe",
+  "render",
+  "keywords",
+  "link",
+  "assemble",
+  "aggregate",
+  "persist",
+  "transfer"
+]);
+var count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+function progressUpdate(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const raw = value;
+  const { phase, state, completed, total, reused, pass, reason } = raw;
+  if (typeof phase !== "string" || !PROGRESS_PHASES.has(phase)) return void 0;
+  if (state !== "start" && state !== "advance" && state !== "end") return void 0;
+  if (completed !== void 0 && !count(completed) || total !== void 0 && !count(total) || reused !== void 0 && !count(reused) || pass !== void 0 && pass !== "targeted" && pass !== "full" && pass !== "restored" || reason !== void 0 && typeof reason !== "string" || completed !== void 0 && total !== void 0 && completed > total || reused !== void 0 && completed !== void 0 && reused > completed)
+    return void 0;
+  return {
+    phase,
+    state,
+    ...completed !== void 0 ? { completed } : {},
+    ...total !== void 0 ? { total } : {},
+    ...reused !== void 0 ? { reused } : {},
+    ...pass !== void 0 ? { pass } : {},
+    ...typeof reason === "string" ? { reason: reason.slice(0, 200) } : {}
+  };
+}
+var ProgressRelay = class {
+  constructor(sink, signal) {
+    this.sink = sink;
+    this.signal = signal;
+    this.transferring = false;
+    this.done = false;
+    /** A compiler update was relayed: a retry of the compile need not ask for progress again. */
+    this.reported = false;
+  }
+  boot(state) {
+    this.emit({ phase: "boot", state });
+  }
+  /** A `progress` message's update, as received. */
+  forward(value) {
+    const update = progressUpdate(value);
+    if (!update || update.phase === "boot" || update.phase === "transfer") return;
+    if (update.state === "start" && update.pass === "full") this.transferring = false;
+    this.emit(update);
+    this.reported = true;
+    if ((update.phase === "persist" || update.phase === "restore" && update.pass === "restored") && update.state === "end" && !this.transferring) {
+      this.transferring = true;
+      this.emit({ phase: "transfer", state: "start" });
+    }
+  }
+  /** The job's result is ready for the caller: the transfer ends and the relay goes quiet. */
+  settled() {
+    if (this.transferring) this.emit({ phase: "transfer", state: "end" });
+    this.done = true;
+  }
+  emit(update) {
+    if (this.done || this.signal.aborted) return;
+    try {
+      this.sink(update);
+    } catch {
+    }
+  }
+};
+
+// libs/builder/generator/worker/index.ts
+var INCREMENTAL_SKIP_ENV = "NGDOC_INCREMENTAL_SKIP";
+function failure(code, message) {
+  return {
+    dependencies: [],
+    diagnostics: [{ code, message, severity: "error", stage: "evaluation" }],
+    whyRebuilt: []
+  };
+}
+function positive(value, fallback) {
+  const number = value ?? fallback;
+  if (!Number.isSafeInteger(number) || number < 1 || number > 2147483647) {
+    throw new Error("Worker limits must be positive timer-safe integers");
+  }
+  return number;
+}
+function bytes(value, fallback) {
+  const number = value ?? fallback;
+  if (!Number.isSafeInteger(number) || number < 1) {
+    throw new Error("Worker memory limits must be positive safe integers");
+  }
+  return number;
+}
+var PROCESS_GROUPS = process.platform !== "win32";
+var GROUP_EXIT_DEADLINE_MS = 2e3;
+function signalRuntime(child, signal) {
+  if (PROCESS_GROUPS && child.pid) {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+    }
+  }
+  child.kill(signal);
+}
+function groupAlive(pid) {
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+async function joinGroup(child) {
+  const pid = child.pid;
+  if (!PROCESS_GROUPS || !pid || !groupAlive(pid)) return;
+  signalRuntime(child, "SIGKILL");
+  const deadline = Date.now() + GROUP_EXIT_DEADLINE_MS;
+  while (groupAlive(pid) && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+var ABORTED = () => failure("WORKER_ABORTED", "Compilation aborted");
+var DISPOSED = () => failure("WORKER_DISPOSED", "Compilation service is disposed");
+var switchedOff = (value) => value !== void 0 && /^(0|false|off|no)$/i.test(value.trim());
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function factoryReuseOff(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && value["incrementalReuse"] === false;
+}
+function primeOutcome(result, reply, aborted) {
+  if (aborted) return { status: "aborted" };
+  const primed = reply !== null && typeof reply === "object" ? reply : {};
+  if (!result.diagnostics.length && typeof primed["revision"] === "string") {
+    return { status: "primed", revision: primed["revision"] };
+  }
+  const code = result.diagnostics[0]?.code ?? String(primed["code"] ?? "WORKER_PROTOCOL");
+  const message = result.diagnostics[0]?.message ?? String(primed["message"] ?? "The warm-up produced no candidate");
+  return { status: "failed", code, message };
+}
+function createWorkerCompilationService(options) {
+  const startupTimeout = positive(options.startupTimeoutMs, 3e4);
+  const compileTimeout = positive(options.compileTimeoutMs, 12e4);
+  const limit = positive(options.maxPendingRequests, 8);
+  const persistentOptions = options["persistent"] === false ? void 0 : options["persistent"] === true || options["persistent"] === void 0 ? {} : options["persistent"];
+  const persistent = persistentOptions && {
+    abortGraceMs: positive(persistentOptions.abortGraceMs, 1500),
+    maxGenerations: positive(persistentOptions.maxGenerations, 50),
+    maxRssBytes: bytes(persistentOptions.maxRssBytes, 3 * 1024 ** 3),
+    prime: persistentOptions.prime !== false,
+    delta: persistentOptions.delta === false ? false : persistentOptions.delta === "verify" ? "verify" : true
+  };
+  const verify = persistent?.delta === "verify";
+  const statistics = {
+    deltas: 0,
+    snapshotResyncs: 0,
+    promotions: 0,
+    fallbacks: 0,
+    mismatches: 0,
+    sentCharacters: 0,
+    receivedCharacters: 0
+  };
+  const dryRuns = { records: 0, misses: 0 };
+  const targetedResults = /* @__PURE__ */ new WeakSet();
+  const dryRunReported = (record2, result) => {
+    if (record2 === null || typeof record2 !== "object") return;
+    dryRuns.records++;
+    dryRuns.last = record2;
+    const { generation, misses, mismatch, published } = record2;
+    if (published === "targeted") targetedResults.add(result);
+    const missed = Array.isArray(misses) && misses.length > 0;
+    if (!missed && typeof mismatch !== "string") return;
+    dryRuns.misses++;
+    process.emitWarning(
+      `Targeted rebuild: generation ${String(generation)}` + (typeof mismatch === "string" ? ` differs from the full generation at ${mismatch}; the full result is published` : "") + (missed ? ` changed ${misses.length} unit(s) outside the targeted closure: ${misses.join(", ")}` : ""),
+      { code: "COMPILATION_TARGETED_MISMATCH" }
+    );
+  };
+  const moduleUrl = new URL(options["moduleUrl"]).href;
+  const workerData = encode({ moduleUrl, factoryOptions: options["factoryOptions"] });
+  const persistentData = encode({
+    moduleUrl,
+    factoryOptions: options["factoryOptions"],
+    persistent: true
+  });
+  const entry = options.workerEntryUrl ?? new URL("./entry.js", import.meta.url);
+  const queue = [];
+  let sequence = 0;
+  let disposed = false;
+  let watching = false;
+  let watchEnded = false;
+  let watchServed = false;
+  let active;
+  let runtime;
+  const runtimes = /* @__PURE__ */ new Set();
+  const ending = () => Promise.all([...runtimes].filter((each) => each !== runtime).map((each) => each.exited)).then(
+    () => void 0
+  );
+  let disposing;
+  const retainedProgramOff = () => switchedOff(process.env[INCREMENTAL_SKIP_ENV]) || factoryReuseOff(options.factoryOptions);
+  function servesStartup(request, context) {
+    return context?.lifetime === "generation" && request?.mode === "development" && persistent?.prime === true && !watching && !watchEnded && !watchServed && !retainedProgramOff();
+  }
+  function pump() {
+    if (active || disposed) return;
+    const job = queue.shift();
+    if (!job) return;
+    if (job.lifetime === "watch" && persistent) runPersistent(job);
+    else runFresh(job);
+  }
+  function runFresh(job) {
+    let worker;
+    try {
+      worker = fork(fileURLToPath(entry), [], {
+        execArgv: [],
+        detached: PROCESS_GROUPS,
+        stdio: ["ignore", "ignore", "ignore", "ipc"],
+        serialization: "json"
+      });
+    } catch (error) {
+      job.signal.removeEventListener("abort", job.abort);
+      job.resolve(failure("WORKER_STARTUP", errorMessage(error)));
+      pump();
+      return;
+    }
+    let ended = false;
+    let completed;
+    let ready = false;
+    let stopped;
+    const stopping = new Promise((resolve) => {
+      stopped = resolve;
+    });
+    let timer;
+    const finish = (result) => {
+      if (ended) return;
+      ended = true;
+      clearTimeout(timer);
+      job.signal.removeEventListener("abort", job.abort);
+      job.progress?.settled();
+      completed = result;
+      signalRuntime(worker, "SIGKILL");
+    };
+    active = {
+      job,
+      abort: () => finish(ABORTED()),
+      dispose: () => finish(DISPOSED()),
+      stopped: stopping
+    };
+    timer = setTimeout(
+      () => finish(failure("WORKER_STARTUP_TIMEOUT", "Compilation worker startup deadline exceeded")),
+      startupTimeout
+    );
+    job.progress?.boot("start");
+    worker.on("message", (message) => {
+      if (ended) return;
+      try {
+        const reply = decode(message);
+        if (reply["type"] === "progress") {
+          if (ready && reply["id"] === job.id) job.progress?.forward(reply["update"]);
+        } else if (reply["type"] === "ready" && !ready) {
+          ready = true;
+          job.progress?.boot("end");
+          clearTimeout(timer);
+          timer = setTimeout(
+            () => finish(failure("WORKER_COMPILE_TIMEOUT", "Compilation deadline exceeded")),
+            compileTimeout
+          );
+          worker.send(job.request, (error) => {
+            if (error) finish(failure("WORKER_PROTOCOL", error.message));
+          });
+        } else if (reply["type"] === "failure" && (!ready || reply["id"] === job.id)) {
+          finish(failure(ready ? "WORKER_COMPILE" : "WORKER_STARTUP", String(reply["message"])));
+        } else if (reply["type"] === "result" && ready && reply["id"] === job.id) {
+          finish(resultFrom(reply["result"]));
+        }
+      } catch (error) {
+        finish(failure("WORKER_PROTOCOL", errorMessage(error)));
+      }
+    });
+    worker.on(
+      "error",
+      (error) => finish(failure(ready ? "WORKER_CRASH" : "WORKER_STARTUP", error.message))
+    );
+    worker.on("close", (code) => {
+      if (!ended)
+        finish(failure("WORKER_EXIT", `Compilation worker exited before replying (${code})`));
+      worker.removeAllListeners();
+      void joinGroup(worker).then(() => {
+        active = void 0;
+        job.resolve(job.signal.aborted ? ABORTED() : disposed ? DISPOSED() : completed);
+        stopped();
+        pump();
+      });
+    });
+    worker.send(workerData, (error) => {
+      if (error) finish(failure("WORKER_STARTUP", error.message));
+    });
+  }
+  function spawn() {
+    const child = fork(fileURLToPath(entry), [], {
+      // Only flag: lets the idle runtime collect a finished generation (see entry.ts).
+      execArgv: ["--expose-gc"],
+      detached: PROCESS_GROUPS,
+      stdio: ["ignore", "ignore", "ignore", "ipc"],
+      // Messages are still JSON text (`encode`), validated and normalised once. With the delta
+      // transport the advanced channel carries that string as is, where a `json` channel would
+      // stringify (escape) and parse it a second time (about half of a large message's
+      // transport). Without it (`delta: false`) the `json` channel is kept.
+      serialization: persistent?.delta ? "advanced" : "json"
+    });
+    let exited;
+    let settleReady;
+    const created = {
+      child,
+      ready: new Promise((resolve) => {
+        settleReady = resolve;
+      }),
+      base: null,
+      committed: null,
+      working: null,
+      delta: false,
+      busy: false,
+      started: false,
+      generations: 0,
+      closed: false,
+      exited: new Promise((resolve) => {
+        exited = resolve;
+      })
+    };
+    runtimes.add(created);
+    let starting = true;
+    const startupFailed = (result) => {
+      if (!starting) return;
+      starting = false;
+      clearTimeout(timer);
+      created.startupFailure = result;
+      settleReady(false);
+      signalRuntime(child, "SIGKILL");
+    };
+    const timer = setTimeout(
+      () => startupFailed(
+        failure("WORKER_STARTUP_TIMEOUT", "Compilation worker startup deadline exceeded")
+      ),
+      startupTimeout
+    );
+    child.on("message", (message) => {
+      if (typeof message === "string") statistics.receivedCharacters += message.length;
+      let reply;
+      try {
+        reply = decode(message);
+      } catch (error) {
+        if (starting) startupFailed(failure("WORKER_PROTOCOL", errorMessage(error)));
+        else created.handler?.({ type: "invalid", message: errorMessage(error) });
+        return;
+      }
+      if (starting) {
+        if (reply["type"] === "ready") {
+          starting = false;
+          clearTimeout(timer);
+          created.started = true;
+          created.delta = reply["delta"] === true;
+          settleReady(true);
+        } else if (reply["type"] === "failure") {
+          startupFailed(failure("WORKER_STARTUP", String(reply["message"])));
+        }
+        return;
+      }
+      if (reply["type"] === "idle") {
+        if (typeof reply["rss"] === "number") {
+          created.idleRss = statistics.idleRss = reply["rss"];
+          if (!created.busy && runtime === created && reply["rss"] > persistent.maxRssBytes) {
+            void retire(created, true);
+            queueMicrotask(prepare);
+          }
+        }
+        return;
+      }
+      if (reply["type"] === "progress") {
+        created.progress?.(reply);
+        return;
+      }
+      created.handler?.({ type: "reply", reply });
+    });
+    child.on("error", (error) => {
+      if (starting) startupFailed(failure("WORKER_STARTUP", error.message));
+      else created.handler?.({ type: "invalid", message: error.message });
+    });
+    child.on("close", (code) => {
+      created.closed = true;
+      startupFailed(failure("WORKER_STARTUP", `Compilation worker exited before ready (${code})`));
+      child.removeAllListeners();
+      if (runtime === created) runtime = void 0;
+      created.handler?.({ type: "close", code });
+      void joinGroup(child).then(() => {
+        runtimes.delete(created);
+        exited();
+      });
+    });
+    child.send(persistentData, (error) => {
+      if (error) startupFailed(failure("WORKER_STARTUP", error.message));
+    });
+    return created;
+  }
+  function retire(target, graceful) {
+    if (runtime === target) runtime = void 0;
+    if (target.closed) return target.exited;
+    if (graceful && persistent) {
+      target.child.send(encode({ type: "dispose" }), () => {
+      });
+      const timer = setTimeout(
+        () => signalRuntime(target.child, "SIGKILL"),
+        persistent.abortGraceMs
+      );
+      void target.exited.then(() => clearTimeout(timer));
+    } else {
+      signalRuntime(target.child, "SIGKILL");
+    }
+    return target.exited;
+  }
+  function prepare() {
+    if (!persistent || disposed || !watching || runtime) return;
+    try {
+      runtime = spawn();
+    } catch {
+    }
+  }
+  function next(target, accept, timeoutMs) {
+    let timer;
+    let settle;
+    const event = new Promise((resolve) => {
+      settle = resolve;
+    });
+    const done = (value) => {
+      clearTimeout(timer);
+      if (target.handler === handler) target.handler = void 0;
+      settle(value);
+    };
+    const handler = (value) => {
+      if (value.type === "reply" && !accept(value.reply)) return;
+      done(value);
+    };
+    if (target.closed) settle({ type: "close", code: null });
+    else {
+      target.handler = handler;
+      timer = setTimeout(() => done({ type: "timeout" }), timeoutMs);
+    }
+    return { event };
+  }
+  function send(target, message) {
+    target.child.send(message, (error) => {
+      if (error) target.handler?.({ type: "invalid", message: error.message });
+    });
+  }
+  function observe(target, reply) {
+    const state = record(reply["state"]);
+    if (state && (state["base"] === null || typeof state["base"] === "string"))
+      target.base = state["base"];
+    target.committed = typeof state?.["committed"] === "string" ? state["committed"] : null;
+    target.working = typeof state?.["working"] === "string" ? state["working"] : null;
+    if (target.committedSource?.revision !== target.committed) target.committedSource = void 0;
+    if (target.workingSource?.revision !== target.working) target.workingSource = void 0;
+  }
+  function runPersistent(job) {
+    let stopped;
+    const stopping = new Promise((resolve) => {
+      stopped = resolve;
+    });
+    let abortRequested;
+    let killed = false;
+    let target;
+    const kill = () => {
+      killed = true;
+      if (target) void retire(target, false);
+    };
+    active = {
+      job,
+      abort: () => abortRequested?.(),
+      dispose: kill,
+      stopped: stopping
+    };
+    const broken = async (current, message) => {
+      void retire(current, false);
+      await current.exited;
+      return failure("WORKER_PROTOCOL", message);
+    };
+    const exchange = async (current, id, message) => {
+      const replied = next(
+        current,
+        (reply) => (reply["type"] === "result" || reply["type"] === "failure") && reply["id"] === id,
+        compileTimeout
+      );
+      const relay = job.progress;
+      current.progress = relay ? (reply) => {
+        if (reply["id"] === id) relay.forward(reply["update"]);
+      } : void 0;
+      abortRequested = () => {
+        abortRequested = void 0;
+        send(current, encode({ type: "abort", id }));
+        const grace = setTimeout(() => {
+          if (!current.closed) void retire(current, false);
+        }, persistent.abortGraceMs);
+        void replied.event.then(() => clearTimeout(grace));
+      };
+      send(current, message);
+      const event = await replied.event;
+      current.progress = void 0;
+      if (event.type === "timeout") {
+        void retire(current, false);
+        await current.exited;
+        return {
+          result: job.signal.aborted ? ABORTED() : failure("WORKER_COMPILE_TIMEOUT", "Compilation deadline exceeded")
+        };
+      }
+      if (event.type === "close") {
+        return {
+          result: failure(
+            "WORKER_EXIT",
+            `Compilation worker exited before replying (${event.code})`
+          )
+        };
+      }
+      if (event.type === "invalid") return { result: await broken(current, event.message) };
+      return { reply: event.reply };
+    };
+    const resync = async (current, snapshot) => {
+      let message;
+      try {
+        message = encode({
+          type: "resync",
+          base: job.base,
+          ...snapshot ? { snapshot } : {},
+          ...snapshot && verify ? { verify: true } : {}
+        });
+      } catch (error) {
+        return failure("WORKER_INPUT", errorMessage(error));
+      }
+      const resynced = next(
+        current,
+        (reply) => reply["type"] === "resynced",
+        snapshot ? compileTimeout : startupTimeout
+      );
+      send(current, message);
+      if (job.delta) statistics.sentCharacters += message.length;
+      const event = await resynced.event;
+      if (event.type !== "reply" || event.reply["base"] !== job.base || snapshot && record(event.reply["state"])?.["committed"] !== job.base) {
+        void retire(current, false);
+        if (killed || disposed) return DISPOSED();
+        return event.type === "close" ? failure("WORKER_EXIT", `Compilation worker exited before replying (${event.code})`) : failure("WORKER_PROTOCOL", "Compilation worker did not acknowledge the base revision");
+      }
+      current.base = job.base;
+      observe(current, event.reply);
+      current.promote = void 0;
+      current.workingSource = void 0;
+      current.committedSource = snapshot && job.base !== null ? { revision: job.base, snapshot: new WeakRef(snapshot) } : void 0;
+      if (snapshot) statistics.snapshotResyncs++;
+      return void 0;
+    };
+    const served = (current, reply, result) => {
+      current.generations++;
+      if (typeof reply["rss"] === "number") statistics.replyRss = reply["rss"];
+      if (reply["dryRun"] !== void 0) dryRunReported(reply["dryRun"], result);
+      recycle(current, reply);
+      return result;
+    };
+    const runFull = async (current) => {
+      if (current.base !== job.base) {
+        const failed = await resync(current, void 0);
+        if (failed) return failed;
+      }
+      if (job.signal.aborted) return ABORTED();
+      const out = await exchange(current, job.id, job.request);
+      if ("result" in out) return out.result;
+      const reply = out.reply;
+      observe(current, reply);
+      if (reply["type"] === "failure") {
+        if (reply["code"] === "WORKER_BASE_MISMATCH")
+          return broken(current, String(reply["message"]));
+        return served(current, reply, failure("WORKER_COMPILE", String(reply["message"])));
+      }
+      let result;
+      try {
+        result = resultFrom(reply["result"]);
+        if (job.prime) job.prime.reply = reply["primed"];
+      } catch (error) {
+        return broken(current, errorMessage(error));
+      }
+      return served(current, reply, result);
+    };
+    const runDelta = async (current) => {
+      const { previous, host } = job.delta;
+      let full = false;
+      for (let attempt = 0; ; attempt++) {
+        const promoting = !full && current.promote !== void 0 && current.promote === job.base && current.working === job.base && current.workingSource?.snapshot.deref() === previous;
+        const retained = current.base === job.base && (job.base === null || current.committed === job.base && current.committedSource?.snapshot.deref() === previous);
+        if (!promoting && !retained) {
+          const failed = await resync(current, job.base === null ? void 0 : previous);
+          if (failed) return failed;
+        }
+        if (job.signal.aborted) return ABORTED();
+        current.promote = void 0;
+        if (promoting) statistics.promotions++;
+        const id = attempt ? ++sequence : job.id;
+        const head = encode({
+          type: "compile",
+          id,
+          base: job.base,
+          delta: true,
+          ...job.base !== null ? { retained: true } : {},
+          ...promoting ? { promote: job.base } : {},
+          ...full ? { full: true } : {},
+          ...verify ? { verify: true } : {},
+          ...job.prime ? { prime: true } : {},
+          // A retry compiles again from the start: it reports its phases only when the first
+          // attempt reported none (it failed before compiling), never a second sequence.
+          ...job.progress && (!attempt || !job.progress.reported) ? { progress: true } : {},
+          host
+        });
+        const message = `${head.slice(0, -1)},"request":${job.request}}`;
+        statistics.sentCharacters += message.length;
+        const out = await exchange(current, id, message);
+        if ("result" in out) return out.result;
+        const reply = out.reply;
+        observe(current, reply);
+        if (previous && job.base !== null && current.committed === job.base)
+          current.committedSource = { revision: job.base, snapshot: new WeakRef(previous) };
+        if (reply["type"] === "failure") {
+          if (reply["code"] === "WORKER_RESYNC_REQUIRED" || reply["code"] === "WORKER_BASE_MISMATCH") {
+            if (attempt) return broken(current, String(reply["message"]));
+            statistics.fallbacks++;
+            current.committed = null;
+            continue;
+          }
+          return served(current, reply, failure("WORKER_COMPILE", String(reply["message"])));
+        }
+        let result;
+        try {
+          result = resultFrom(reply["result"]);
+        } catch (error) {
+          return broken(current, errorMessage(error));
+        }
+        if (job.prime) {
+          job.prime.reply = reply["primed"];
+          return served(current, reply, result);
+        }
+        if (reply["delta"] === void 0) return served(current, reply, result);
+        let candidate;
+        try {
+          candidate = applySnapshotDelta(previous, reply["delta"]);
+        } catch (error) {
+          if (attempt) return broken(current, errorMessage(error));
+          statistics.fallbacks++;
+          current.generations++;
+          current.committed = null;
+          current.working = null;
+          full = true;
+          continue;
+        }
+        let replaced = false;
+        if (verify) {
+          if (JSON.stringify(candidate) !== JSON.stringify(reply["full"])) {
+            statistics.mismatches++;
+            candidate = reply["full"];
+            current.committed = null;
+            current.working = null;
+            current.committedSource = void 0;
+            current.workingSource = void 0;
+            replaced = true;
+          }
+          deepFreeze(candidate);
+        }
+        if (!replaced) {
+          statistics.deltas++;
+          if (current.working === candidate.revision)
+            current.workingSource = {
+              revision: candidate.revision,
+              snapshot: new WeakRef(candidate)
+            };
+        }
+        return served(current, reply, { ...result, candidate });
+      }
+    };
+    const run = async () => {
+      try {
+        target = runtime && !runtime.closed ? runtime : runtime = spawn();
+      } catch (error) {
+        return failure("WORKER_STARTUP", errorMessage(error));
+      }
+      const current = target;
+      current.busy = true;
+      const aborted = new Promise((resolve) => {
+        abortRequested = () => resolve(false);
+        if (job.signal.aborted) resolve(false);
+      });
+      const booting = !current.started;
+      if (booting) job.progress?.boot("start");
+      const ready = await Promise.race([current.ready, aborted]);
+      if (booting && ready) job.progress?.boot("end");
+      if (killed || disposed) return DISPOSED();
+      if (job.signal.aborted) return ABORTED();
+      if (!ready) return current.startupFailure ?? failure("WORKER_STARTUP", "Worker is not ready");
+      if (!job.delta) return runFull(current);
+      if (current.delta) return runDelta(current);
+      const { previous, host } = job.delta;
+      let request = job.request;
+      try {
+        if (previous)
+          request = `${request.slice(0, -1)}${request.length > 2 ? "," : ""}"previous":${encode(previous)}}`;
+      } catch (error) {
+        return failure("WORKER_INPUT", errorMessage(error));
+      }
+      const head = encode({
+        type: "compile",
+        id: job.id,
+        base: job.base,
+        host,
+        ...job.prime ? { prime: true } : {},
+        ...job.progress ? { progress: true } : {}
+      });
+      job.request = `${head.slice(0, -1)},"request":${request}}`;
+      delete job.delta;
+      return runFull(current);
+    };
+    void run().catch((error) => failure("WORKER_PROTOCOL", errorMessage(error))).then(async (result) => {
+      if (killed && target && !target.closed) await target.exited;
+      if (target) target.busy = false;
+      if (target && target === runtime && !target.closed && (target.idleRss ?? 0) > persistent.maxRssBytes) {
+        void retire(target, true);
+        queueMicrotask(prepare);
+      }
+      job.signal.removeEventListener("abort", job.abort);
+      job.progress?.settled();
+      active = void 0;
+      job.resolve(job.signal.aborted ? ABORTED() : disposed ? DISPOSED() : result);
+      stopped();
+      if (watchEnded && runtime && !queue.some((next2) => next2.lifetime === "watch")) {
+        void retire(runtime, true);
+      }
+      pump();
+    });
+  }
+  function recycle(target, reply) {
+    const rss = target.delta ? 0 : typeof reply["rss"] === "number" ? reply["rss"] : 0;
+    if (reply["recycle"] !== true && target.generations < persistent.maxGenerations && rss <= persistent.maxRssBytes)
+      return;
+    void retire(target, true);
+    queueMicrotask(prepare);
+  }
+  const service = {
+    compile(request, signal, context) {
+      if (disposed) return Promise.resolve(DISPOSED());
+      if (signal.aborted) return Promise.resolve(ABORTED());
+      const priming = active?.job.prime;
+      if (queue.length + Number(Boolean(active) && !priming) >= limit) {
+        return Promise.resolve(
+          failure("WORKER_QUEUE_FULL", "Compilation pending-request limit exceeded")
+        );
+      }
+      let serialized;
+      let delta;
+      const id = ++sequence;
+      if (context?.lifetime === "watch") watchServed = true;
+      const lifetime = context?.lifetime === "watch" || servesStartup(request, context) ? "watch" : "generation";
+      const base = typeof request?.previous?.revision === "string" ? request.previous.revision : null;
+      const sink = context?.progress;
+      const progress = typeof sink === "function" ? new ProgressRelay(sink, signal) : void 0;
+      const wanted = progress ? { progress: true } : {};
+      try {
+        const host = () => ({ env: { ...process.env }, cwd: process.cwd() });
+        if (lifetime === "watch" && persistent?.delta && context?.delta === true) {
+          const { previous, ...rest } = request;
+          serialized = encode(rest);
+          delta = { ...previous ? { previous } : {}, host: host() };
+        } else {
+          serialized = encode(
+            lifetime === "watch" && persistent ? { type: "compile", id, base, request, host: host(), ...wanted } : { type: "compile", id, request, ...wanted }
+          );
+        }
+      } catch (error) {
+        return Promise.resolve(failure("WORKER_INPUT", errorMessage(error)));
+      }
+      return new Promise((resolve) => {
+        const job = {
+          id,
+          request: serialized,
+          base,
+          lifetime,
+          ...delta ? { delta } : {},
+          ...progress ? { progress } : {},
+          signal,
+          resolve,
+          abort() {
+            if (active?.job === job) {
+              active.abort();
+            } else {
+              const index = queue.indexOf(job);
+              if (index >= 0) queue.splice(index, 1);
+              signal.removeEventListener("abort", job.abort);
+              resolve(ABORTED());
+            }
+          }
+        };
+        signal.addEventListener("abort", job.abort, { once: true });
+        queue.push(job);
+        priming?.supersede();
+        pump();
+      });
+    },
+    prime(request, signal) {
+      const skipped = (reason) => Promise.resolve({ status: "skipped", reason });
+      if (disposed || !watching) return skipped("not watching");
+      if (active || queue.length) return skipped("busy");
+      if (retainedProgramOff()) return skipped("retained program disabled");
+      if (request?.mode !== "development" || typeof request.previous?.revision !== "string")
+        return skipped("not a development request with a previous snapshot");
+      if (signal.aborted) return Promise.resolve({ status: "aborted" });
+      const id = ++sequence;
+      const base = request.previous.revision;
+      const host = { env: { ...process.env }, cwd: process.cwd() };
+      let serialized;
+      let delta;
+      try {
+        if (persistent.delta) {
+          const { previous, ...rest } = request;
+          serialized = encode(rest);
+          delta = { previous, host };
+        } else {
+          serialized = encode({ type: "compile", id, base, request, host, prime: true });
+        }
+      } catch (error) {
+        return Promise.resolve({
+          status: "failed",
+          code: "WORKER_INPUT",
+          message: errorMessage(error)
+        });
+      }
+      const controller = new AbortController();
+      const forward = () => controller.abort();
+      signal.addEventListener("abort", forward, { once: true });
+      return new Promise((resolve) => {
+        const job = {
+          id,
+          request: serialized,
+          base,
+          lifetime: "watch",
+          ...delta ? { delta } : {},
+          prime: { supersede: () => controller.abort() },
+          signal: controller.signal,
+          resolve(result) {
+            signal.removeEventListener("abort", forward);
+            resolve(primeOutcome(result, job.prime.reply, controller.signal.aborted || disposed));
+          },
+          abort() {
+            if (active?.job === job) active.abort();
+          }
+        };
+        controller.signal.addEventListener("abort", job.abort, { once: true });
+        queue.push(job);
+        pump();
+      });
+    },
+    acknowledge(acknowledgement) {
+      const current = runtime;
+      if (!current || current.closed) return;
+      current.promote = acknowledgement?.status === "committed" && acknowledgement.revision === current.working ? current.working : void 0;
+    },
+    transport() {
+      return { ...statistics };
+    },
+    targetedResult: (result) => targetedResults.has(result),
+    targetedDryRun() {
+      return structuredClone(dryRuns);
+    },
+    watching(value) {
+      watching = value && !disposed;
+      watchEnded = !watching;
+      if (watching) {
+        prepare();
+        return Promise.resolve();
+      }
+      active?.job.prime?.supersede();
+      if (active?.job.lifetime === "watch") return active.stopped.then(ending);
+      if (runtime) void retire(runtime, true);
+      return ending();
+    },
+    dispose() {
+      if (disposing) return disposing;
+      disposed = true;
+      watching = false;
+      for (const job of queue.splice(0)) {
+        job.signal.removeEventListener("abort", job.abort);
+        job.resolve(DISPOSED());
+      }
+      const running = active;
+      running?.dispose();
+      disposing = Promise.all([
+        running?.stopped ?? Promise.resolve(),
+        ...[...runtimes].map((each) => retire(each, false))
+      ]).then(() => void 0);
+      return disposing;
+    }
+  };
+  if (!persistent?.prime) delete service.prime;
+  if (!persistent?.delta) delete service.acknowledge;
+  return service;
+}
+export {
+  createWorkerCompilationService
+};