wiki-graph-core 0.3.1

package/dist/facade/build-queue.js

@@ -0,0 +1,1442 @@
+import { createHash, randomUUID } from "crypto";
+import { appendFile, mkdir, readFile, rm } from "fs/promises";
+import { join, resolve } from "path";
+import { resolveWikiGraphJobsDirectoryPath } from "../common/wiki-graph-dir.js";
+import { openSharedStateDatabase } from "../document/index.js";
+import { readPathSize, removeDisposableChildDirectories } from "../gc/files.js";
+const BUILD_JOB_STATES = [
+  "queued",
+  "running",
+  "canceling",
+  "paused",
+  "succeeded",
+  "failed",
+  "canceled"
+];
+const BUILD_QUEUE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS build_jobs (
+  job_id TEXT PRIMARY KEY,
+  archive_key TEXT NOT NULL,
+  archive_path TEXT NOT NULL,
+  chapter_id INTEGER NOT NULL,
+  target TEXT NOT NULL,
+  current_step TEXT,
+  state TEXT NOT NULL,
+  queue_rank INTEGER NOT NULL,
+  workspace_path TEXT NOT NULL,
+  cache_path TEXT NOT NULL,
+  log_path TEXT NOT NULL,
+  events_path TEXT NOT NULL,
+  input_revision INTEGER,
+  llm_json TEXT,
+  prompt TEXT,
+  owner_id TEXT,
+  owner_pid INTEGER,
+  reading_summary_started_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  finished_at INTEGER,
+  error_json TEXT
+);
+
+DROP INDEX IF EXISTS idx_build_jobs_active_chapter;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_build_jobs_active_knowledge_chapter
+ON build_jobs(archive_key, chapter_id)
+WHERE target = 'knowledge-graph'
+  AND state IN ('queued', 'running', 'canceling', 'paused');
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_build_jobs_active_reading_chapter
+ON build_jobs(archive_key, chapter_id)
+WHERE target IN ('reading-graph', 'reading-summary')
+  AND state IN ('queued', 'running', 'canceling', 'paused');
+
+CREATE INDEX IF NOT EXISTS idx_build_jobs_queue
+ON build_jobs(state, queue_rank, updated_at);
+
+CREATE TABLE IF NOT EXISTS build_worker_lease (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  owner_id TEXT,
+  owner_pid INTEGER,
+  heartbeat_at INTEGER
+);
+
+INSERT OR IGNORE INTO build_worker_lease (id)
+VALUES (1);
+`;
+const ACTIVE_JOB_STATES = /* @__PURE__ */ new Set([
+  "queued",
+  "running",
+  "canceling",
+  "paused"
+]);
+const WORKER_HEARTBEAT_INTERVAL_MS = 5e3;
+async function addBuildJob(options) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    return await state.transaction(async () => {
+      const archivePath = resolve(options.archivePath);
+      const archiveKey = createArchiveKey(archivePath);
+      const now = Date.now();
+      const existing = await findActiveBuildJobInLane(state, {
+        archiveKey,
+        chapterId: options.chapterId,
+        target: options.target
+      });
+      if (existing !== void 0) {
+        return await mergeActiveBuildJob(state, existing, options, now);
+      }
+      const jobId = options.jobId ?? randomUUID();
+      const workspacePath = await createJobWorkspacePath(jobId);
+      const cachePath = await createJobCachePath(jobId);
+      const logPath = await createJobLogPath(jobId);
+      const eventsPath = await createJobEventsPath(jobId);
+      const queueRank = options.boost === true ? await readMinQueueRank(state) - 1 : await readMaxQueueRank(state) + 1;
+      await state.run(
+        `
+INSERT INTO build_jobs (
+  job_id, archive_key, archive_path, chapter_id, target, state, queue_rank,
+  workspace_path, cache_path, log_path, events_path, llm_json, prompt,
+  created_at, updated_at
+) VALUES (?, ?, ?, ?, ?, 'queued', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+`,
+        [
+          jobId,
+          archiveKey,
+          archivePath,
+          options.chapterId,
+          options.target,
+          queueRank,
+          workspacePath,
+          cachePath,
+          logPath,
+          eventsPath,
+          options.llmJSON ?? null,
+          options.prompt ?? null,
+          now,
+          now
+        ]
+      );
+      const job = await requireBuildJobById(state, jobId);
+      await appendBuildJobEvent(job, {
+        at: now,
+        jobId,
+        seq: 0,
+        state: "queued",
+        type: "created"
+      });
+      return job;
+    });
+  } finally {
+    await state.close();
+  }
+}
+async function recordBuildJobInputRevision(input) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await state.transaction(async () => {
+      await state.run(
+        `
+UPDATE build_jobs
+SET input_revision = ?,
+    updated_at = ?
+WHERE job_id = ?
+  AND owner_id = ?
+  AND state = 'running'
+`,
+        [input.currentRevision, Date.now(), input.jobId, input.ownerId]
+      );
+    });
+    return await requireBuildJobById(state, input.jobId);
+  } finally {
+    await state.close();
+  }
+}
+async function assertBuildJobInputRevision(input) {
+  const job = await getBuildJob(input.jobId);
+  if (job.state !== "running" || job.ownerId !== input.ownerId) {
+    throw new BuildJobStoppedError(
+      `Job ${input.jobId} is ${job.state}. Stop current worker execution.`
+    );
+  }
+  if (job.inputRevision === void 0) {
+    throw new Error(
+      `Job ${input.jobId} has no recorded chapter input revision. Requeue the job before committing build output.`
+    );
+  }
+  if (job.inputRevision === input.currentRevision) {
+    return;
+  }
+  throw new Error(
+    `Chapter ${job.chapterId} changed while job ${job.jobId} was running. Requeue the job before committing build output.`
+  );
+}
+async function listBuildJobs(options = {}) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    const params = [];
+    const filters = [];
+    if (options.archivePath !== void 0) {
+      params.push(createArchiveKey(resolve(options.archivePath)));
+      filters.push("archive_key = ?");
+    }
+    if (options.activeOnly === true || options.all !== true) {
+      filters.push("state IN ('queued', 'running', 'canceling', 'paused')");
+    }
+    return await state.queryAll(
+      `
+SELECT *
+FROM build_jobs
+${filters.length === 0 ? "" : `WHERE ${filters.join(" AND ")}`}
+ORDER BY
+  CASE state
+    WHEN 'running' THEN 0
+    WHEN 'canceling' THEN 1
+    WHEN 'queued' THEN 2
+    WHEN 'paused' THEN 3
+    ELSE 4
+  END,
+  queue_rank ASC,
+  updated_at DESC
+`,
+      params,
+      mapBuildJob
+    );
+  } finally {
+    await state.close();
+  }
+}
+async function findActiveBuildJobInLane(state, input) {
+  const laneFilter = input.target === "knowledge-graph" ? "target = 'knowledge-graph'" : "target IN ('reading-graph', 'reading-summary')";
+  return await state.queryOne(
+    `
+SELECT *
+FROM build_jobs
+WHERE archive_key = ?
+  AND chapter_id = ?
+  AND state IN ('queued', 'running', 'canceling', 'paused')
+  AND ${laneFilter}
+ORDER BY updated_at DESC
+LIMIT 1
+`,
+    [input.archiveKey, input.chapterId],
+    mapBuildJob
+  );
+}
+async function mergeActiveBuildJob(state, job, options, now) {
+  const nextTarget = job.target === "reading-graph" && options.target === "reading-summary" ? "reading-summary" : job.target;
+  const nextQueueRank = options.boost === true && job.state === "queued" ? await readMinQueueRank(state) - 1 : job.queueRank;
+  if (nextTarget === job.target && nextQueueRank === job.queueRank) {
+    return job;
+  }
+  await state.run(
+    `
+UPDATE build_jobs
+SET target = ?, queue_rank = ?, updated_at = ?
+WHERE job_id = ?
+`,
+    [nextTarget, nextQueueRank, now, job.jobId]
+  );
+  const updated = await requireBuildJobById(state, job.jobId);
+  if (nextTarget !== job.target) {
+    await appendBuildJobEvent(updated, {
+      at: now,
+      from: job.target,
+      jobId: job.jobId,
+      seq: 0,
+      to: nextTarget,
+      type: "target_changed"
+    });
+  }
+  if (nextQueueRank !== job.queueRank) {
+    await appendBuildJobEvent(updated, {
+      at: now,
+      jobId: job.jobId,
+      seq: 0,
+      state: updated.state,
+      type: "boosted"
+    });
+  }
+  return updated;
+}
+async function getBuildJob(jobId) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    return await requireBuildJobById(state, jobId);
+  } finally {
+    await state.close();
+  }
+}
+async function readBuildJobForStopCheck(jobId) {
+  const state = await openReadonlyBuildQueueDatabase();
+  try {
+    return await requireBuildJobById(state, jobId);
+  } finally {
+    await state.close();
+  }
+}
+async function resolveBuildJobId(jobIdPrefix) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    return await resolveBuildJobIdInState(state, jobIdPrefix);
+  } finally {
+    await state.close();
+  }
+}
+async function pauseBuildJob(jobId) {
+  return await updateBuildJobState(jobId, "paused", "paused", {
+    allowedStates: ["queued", "running"]
+  });
+}
+async function resumeBuildJob(jobId) {
+  return await updateBuildJobState(jobId, "queued", "resumed", {
+    allowedStates: ["paused"],
+    clearOwner: true
+  });
+}
+async function cancelBuildJob(jobId) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    return await state.transaction(async () => {
+      const job = await requireBuildJobById(state, jobId);
+      if (job.state === "running") {
+        return await markBuildJobCanceling(state, job);
+      }
+      if (job.state === "queued" || job.state === "paused") {
+        return await markBuildJobCanceled(state, job);
+      }
+      throw new Error(`Cannot cancel ${job.state} job ${jobId}.`);
+    });
+  } finally {
+    await state.close();
+  }
+}
+async function boostBuildJob(jobId) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    return await state.transaction(async () => {
+      const job = await requireBuildJobById(state, jobId);
+      if (job.state !== "queued") {
+        throw new Error(
+          `Only queued jobs can be boosted. Job ${jobId} is ${job.state}.`
+        );
+      }
+      const now = Date.now();
+      await state.run(
+        `
+UPDATE build_jobs
+SET queue_rank = ?, updated_at = ?
+WHERE job_id = ?
+`,
+        [await readMinQueueRank(state) - 1, now, jobId]
+      );
+      const updated = await requireBuildJobById(state, jobId);
+      await appendBuildJobEvent(updated, {
+        at: now,
+        jobId,
+        seq: 0,
+        state: "queued",
+        type: "boosted"
+      });
+      return updated;
+    });
+  } finally {
+    await state.close();
+  }
+}
+async function updateBuildJobTarget(jobId, target) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    return await state.transaction(async () => {
+      const job = await requireBuildJobById(state, jobId);
+      if (!ACTIVE_JOB_STATES.has(job.state)) {
+        throw new Error(`Cannot change target for ${job.state} job ${jobId}.`);
+      }
+      if (job.target === target) {
+        return job;
+      }
+      const existing = await findActiveBuildJobInLane(state, {
+        archiveKey: job.archiveKey,
+        chapterId: job.chapterId,
+        target
+      });
+      if (existing !== void 0 && existing.jobId !== job.jobId) {
+        throw new Error(
+          `Chapter ${job.chapterId} already has active ${formatBuildJobLane(target)} job ${existing.jobId}.`
+        );
+      }
+      if (job.target === "reading-summary" && target === "reading-graph") {
+        if (job.readingSummaryStartedAt !== void 0 || job.currentStep === "reading-summary") {
+          throw new Error(
+            `Cannot downgrade job ${jobId} after summary has started. Cancel it explicitly instead.`
+          );
+        }
+      }
+      const now = Date.now();
+      await state.run(
+        `
+UPDATE build_jobs
+SET target = ?, updated_at = ?
+WHERE job_id = ?
+`,
+        [target, now, jobId]
+      );
+      const updated = await requireBuildJobById(state, jobId);
+      await appendBuildJobEvent(updated, {
+        at: now,
+        from: job.target,
+        jobId,
+        seq: 0,
+        to: target,
+        type: "target_changed"
+      });
+      return updated;
+    });
+  } finally {
+    await state.close();
+  }
+}
+async function assertNoActiveBuildJobs(input) {
+  await assertNoActiveBuildJobConflicts({
+    archivePath: input.archivePath,
+    operation: input.operation,
+    ...input.requiresTarget === void 0 ? {} : { requiresTarget: input.requiresTarget },
+    scope: { chapterIds: input.chapterIds, kind: "chapter" }
+  });
+}
+async function assertNoActiveBuildJobConflicts(input) {
+  if (input.scope.kind === "chapter" && input.scope.chapterIds.length === 0) {
+    return;
+  }
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    const archiveKey = createArchiveKey(resolve(input.archivePath));
+    const targetFilter = input.requiresTarget === void 0 ? "" : "AND target = ?";
+    const params = [archiveKey];
+    let scopeFilter = "";
+    if (input.scope.kind === "chapter") {
+      const placeholders = input.scope.chapterIds.map(() => "?").join(", ");
+      scopeFilter = `AND chapter_id IN (${placeholders})`;
+      params.push(...input.scope.chapterIds);
+    }
+    if (input.requiresTarget !== void 0) {
+      params.push(input.requiresTarget);
+    }
+    const job = await state.queryOne(
+      `
+SELECT *
+FROM build_jobs
+WHERE archive_key = ?
+  ${scopeFilter}
+  AND state IN ('queued', 'running', 'canceling', 'paused')
+  ${targetFilter}
+ORDER BY updated_at DESC
+LIMIT 1
+`,
+      params,
+      mapBuildJob
+    );
+    if (job === void 0) {
+      return;
+    }
+    throw new Error(
+      `Chapter ${job.chapterId} has active ${job.target} job ${job.jobId}. ${input.operation} is blocked until the job is paused/canceled or completed.`
+    );
+  } finally {
+    await state.close();
+  }
+}
+async function runBuildJobWorker(options) {
+  const state = await openBuildQueueDatabase();
+  const ownerId = `${process.pid}-${randomUUID()}`;
+  const concurrency = Math.max(1, options.concurrency);
+  const idleTimeoutMs = options.idleTimeoutMs ?? 1e4;
+  let stopping = false;
+  let busySlotCount = 0;
+  let idleSince = Date.now();
+  const stop = (_signal) => {
+    stopping = true;
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  const heartbeat = setInterval(() => {
+    void heartbeatBuildWorker(ownerId).catch(() => void 0);
+  }, WORKER_HEARTBEAT_INTERVAL_MS);
+  try {
+    const acquired = await acquireBuildWorkerLease(state, ownerId);
+    if (!acquired) {
+      return;
+    }
+    const runSlot = async () => {
+      while (!stopping) {
+        await heartbeatBuildWorker(ownerId, state);
+        await recoverStaleBuildJobs(state);
+        busySlotCount += 1;
+        let job;
+        try {
+          job = await claimQueuedBuildJob(state, ownerId);
+        } finally {
+          if (job === void 0) {
+            busySlotCount -= 1;
+          }
+        }
+        if (job === void 0) {
+          if (busySlotCount === 0 && Date.now() - idleSince >= idleTimeoutMs) {
+            break;
+          }
+          await delay(500);
+          continue;
+        }
+        idleSince = Date.now();
+        try {
+          await executeClaimedBuildJob(job, ownerId, options);
+        } finally {
+          busySlotCount -= 1;
+          if (busySlotCount === 0) {
+            idleSince = Date.now();
+          }
+        }
+      }
+    };
+    await Promise.all(
+      Array.from({ length: concurrency }, async () => await runSlot())
+    );
+  } finally {
+    clearInterval(heartbeat);
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+    await releaseBuildWorkerLease(state, ownerId);
+    await state.close();
+  }
+}
+async function executeClaimedBuildJob(job, ownerId, options) {
+  const reporter = new BuildJobProgressAccumulator(job, ownerId);
+  const abortController = new AbortController();
+  const stopWatcher = setInterval(() => {
+    void abortJobWhenStopped(job, ownerId, abortController).catch(
+      () => void 0
+    );
+  }, 500);
+  try {
+    await appendBuildJobEvent(job, {
+      at: Date.now(),
+      jobId: job.jobId,
+      seq: 0,
+      state: "running",
+      type: "started"
+    });
+    await options.executeJob(job, reporter, {
+      signal: abortController.signal
+    });
+    await reporter.throwIfStopped();
+    await markBuildJobSucceeded(job.jobId, ownerId);
+  } catch (error) {
+    if (error instanceof BuildJobStoppedError || abortController.signal.aborted) {
+      await markBuildJobStopped(job.jobId, ownerId);
+      return;
+    }
+    await markBuildJobFailed(job.jobId, ownerId, error);
+  } finally {
+    clearInterval(stopWatcher);
+  }
+}
+async function abortJobWhenStopped(job, ownerId, abortController) {
+  if (abortController.signal.aborted) {
+    return;
+  }
+  const latest = await readBuildJobForStopCheck(job.jobId);
+  if (latest.state === "running" && latest.ownerId === ownerId) {
+    return;
+  }
+  abortController.abort(
+    new BuildJobStoppedError(
+      `Job ${job.jobId} is ${latest.state}. Stop current worker execution.`
+    )
+  );
+}
+async function readBuildJobEvents(job) {
+  let content;
+  try {
+    content = await readFile(job.eventsPath, "utf8");
+  } catch {
+    return [];
+  }
+  return content.split("\n").filter((line) => line.trim() !== "").map((line) => JSON.parse(line));
+}
+async function cleanBuildJobs(options = {}) {
+  const state = await openBuildQueueDatabase();
+  const cutoff = Date.now() - (options.olderThanMs ?? 7 * 24 * 60 * 60 * 1e3);
+  const states = options.states ?? ["succeeded", "failed", "canceled"];
+  try {
+    const placeholders = states.map(() => "?").join(", ");
+    const jobs = await state.queryAll(
+      `
+SELECT *
+FROM build_jobs
+WHERE state IN (${placeholders})
+  AND updated_at <= ?
+`,
+      [...states, cutoff],
+      mapBuildJob
+    );
+    for (const job of jobs) {
+      await rm(job.workspacePath, { force: true, recursive: true });
+      await rm(job.cachePath, { force: true, recursive: true });
+      await rm(job.logPath, { force: true, recursive: true });
+      await rm(job.eventsPath, { force: true });
+      await state.run("DELETE FROM build_jobs WHERE job_id = ?", [job.jobId]);
+    }
+    return jobs.length;
+  } finally {
+    await state.close();
+  }
+}
+async function runBuildQueueGc(context) {
+  const state = await openBuildQueueDatabase();
+  const cutoff = context.force ? context.now : context.now - 7 * 24 * 60 * 60 * 1e3;
+  try {
+    const scanned = await state.queryOne(
+      "SELECT COUNT(*) AS count FROM build_jobs",
+      void 0,
+      (row) => getNumber(row, "count")
+    );
+    const jobs = await state.queryAll(
+      `
+SELECT *
+FROM build_jobs
+WHERE state IN ('succeeded', 'failed', 'canceled')
+  AND updated_at <= ?
+`,
+      [cutoff],
+      mapBuildJob
+    );
+    const childDirectories = context.dryRun ? { freedBytes: 0, removed: 0, scanned: 0 } : await removeDisposableChildDirectories(getBuildJobWorkspaceRootPath());
+    let freedBytes = 0;
+    for (const job of jobs) {
+      freedBytes += await readPathSize(job.workspacePath);
+      freedBytes += await readPathSize(job.cachePath);
+      freedBytes += await readPathSize(job.logPath);
+      freedBytes += await readPathSize(job.eventsPath);
+      if (!context.dryRun) {
+        await rm(job.workspacePath, { force: true, recursive: true });
+        await rm(job.cachePath, { force: true, recursive: true });
+        await rm(job.logPath, { force: true, recursive: true });
+        await rm(job.eventsPath, { force: true });
+        await state.run("DELETE FROM build_jobs WHERE job_id = ?", [job.jobId]);
+      }
+    }
+    return {
+      freedBytes: freedBytes + childDirectories.freedBytes,
+      removed: jobs.length + childDirectories.removed,
+      scanned: (scanned ?? 0) + childDirectories.scanned
+    };
+  } finally {
+    await state.close();
+  }
+}
+async function updateBuildJobState(jobId, stateName, eventType, options) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await recoverStaleBuildJobs(state);
+    return await state.transaction(async () => {
+      const job = await requireBuildJobById(state, jobId);
+      if (!options.allowedStates.includes(job.state)) {
+        throw new Error(`Cannot ${eventType} ${job.state} job ${jobId}.`);
+      }
+      const now = Date.now();
+      await state.run(
+        `
+UPDATE build_jobs
+SET state = ?, updated_at = ?, finished_at = ?,
+    owner_id = CASE WHEN ? = 1 THEN NULL ELSE owner_id END,
+    owner_pid = CASE WHEN ? = 1 THEN NULL ELSE owner_pid END
+WHERE job_id = ?
+`,
+        [
+          stateName,
+          now,
+          options.finished === true ? now : null,
+          options.clearOwner === true || options.finished === true ? 1 : 0,
+          options.clearOwner === true || options.finished === true ? 1 : 0,
+          jobId
+        ]
+      );
+      const updated = await requireBuildJobById(state, jobId);
+      await appendBuildJobEvent(updated, {
+        at: now,
+        jobId,
+        seq: 0,
+        state: stateName,
+        type: eventType
+      });
+      return updated;
+    });
+  } finally {
+    await state.close();
+  }
+}
+async function markBuildJobCanceling(state, job) {
+  const now = Date.now();
+  await state.run(
+    `
+UPDATE build_jobs
+SET state = 'canceling', updated_at = ?
+WHERE job_id = ? AND state = 'running'
+`,
+    [now, job.jobId]
+  );
+  const updated = await requireBuildJobById(state, job.jobId);
+  await appendBuildJobEvent(updated, {
+    at: now,
+    jobId: job.jobId,
+    seq: 0,
+    state: "canceling",
+    type: "canceling"
+  });
+  return updated;
+}
+async function markBuildJobCanceled(state, job) {
+  const now = Date.now();
+  await state.run(
+    `
+UPDATE build_jobs
+SET state = 'canceled', owner_id = NULL, owner_pid = NULL,
+    current_step = NULL, finished_at = ?, updated_at = ?
+WHERE job_id = ?
+`,
+    [now, now, job.jobId]
+  );
+  const updated = await requireBuildJobById(state, job.jobId);
+  await appendBuildJobEvent(updated, {
+    at: now,
+    jobId: job.jobId,
+    seq: 0,
+    state: "canceled",
+    type: "canceled"
+  });
+  return updated;
+}
+async function markBuildJobFailedInState(state, job, error) {
+  const now = Date.now();
+  const formattedError = formatErrorEvent(error);
+  const errorJSON = JSON.stringify(formattedError);
+  await state.run(
+    `
+UPDATE build_jobs
+SET state = 'failed', owner_id = NULL, owner_pid = NULL,
+    current_step = NULL, finished_at = ?, updated_at = ?, error_json = ?
+WHERE job_id = ?
+`,
+    [now, now, errorJSON, job.jobId]
+  );
+  await appendBuildJobEvent(job, {
+    at: now,
+    error: formattedError,
+    jobId: job.jobId,
+    seq: 0,
+    state: "failed",
+    type: "failed"
+  });
+}
+async function markBuildJobSucceeded(jobId, ownerId) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await state.transaction(async () => {
+      const job = await requireBuildJobById(state, jobId);
+      if (job.ownerId !== ownerId || job.state !== "running") {
+        return;
+      }
+      const now = Date.now();
+      await state.run(
+        `
+UPDATE build_jobs
+SET state = 'succeeded', owner_id = NULL, owner_pid = NULL,
+    current_step = NULL, finished_at = ?, updated_at = ?
+WHERE job_id = ?
+`,
+        [now, now, jobId]
+      );
+      await appendBuildJobEvent(job, {
+        at: now,
+        jobId,
+        seq: 0,
+        state: "succeeded",
+        type: "succeeded"
+      });
+      await rm(job.workspacePath, { force: true, recursive: true });
+    });
+  } finally {
+    await state.close();
+  }
+}
+async function markBuildJobFailed(jobId, ownerId, error) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await state.transaction(async () => {
+      const job = await requireBuildJobById(state, jobId);
+      if (job.ownerId !== ownerId || job.state !== "running") {
+        return;
+      }
+      await markBuildJobFailedInState(state, job, error);
+    });
+  } finally {
+    await state.close();
+  }
+}
+async function markBuildJobStopped(jobId, ownerId) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await state.transaction(async () => {
+      const job = await requireBuildJobById(state, jobId);
+      if (job.ownerId !== ownerId || job.state !== "canceling") {
+        return;
+      }
+      await markBuildJobCanceled(state, job);
+    });
+  } finally {
+    await state.close();
+  }
+}
+async function claimQueuedBuildJob(state, ownerId) {
+  return await state.transaction(async () => {
+    const job = await state.queryOne(
+      `
+SELECT *
+FROM build_jobs
+WHERE state = 'queued'
+ORDER BY queue_rank ASC, created_at ASC
+LIMIT 1
+`,
+      void 0,
+      mapBuildJob
+    );
+    if (job === void 0) {
+      return void 0;
+    }
+    const now = Date.now();
+    await state.run(
+      `
+UPDATE build_jobs
+SET state = 'running', owner_id = ?, owner_pid = ?, updated_at = ?
+WHERE job_id = ? AND state = 'queued'
+`,
+      [ownerId, process.pid, now, job.jobId]
+    );
+    return await requireBuildJobById(state, job.jobId);
+  });
+}
+async function recoverStaleBuildJobs(state) {
+  const workspacePathsToDelete = [];
+  await state.transaction(async () => {
+    const jobs = await state.queryAll(
+      `
+SELECT *
+FROM build_jobs
+WHERE state IN ('running', 'canceling')
+  AND owner_pid IS NOT NULL
+`,
+      void 0,
+      mapBuildJob
+    );
+    for (const job of jobs) {
+      if (job.ownerPid !== void 0 && isProcessAlive(job.ownerPid)) {
+        continue;
+      }
+      if (job.state === "canceling") {
+        await markBuildJobCanceled(state, job);
+        continue;
+      }
+      await markBuildJobFailedInState(state, job, {
+        message: "Build worker process disappeared before finishing the job.",
+        name: "BuildJobWorkerLost"
+      });
+      workspacePathsToDelete.push(job.workspacePath);
+    }
+  });
+  for (const workspacePath of workspacePathsToDelete) {
+    await rm(workspacePath, { force: true, recursive: true });
+  }
+}
+async function acquireBuildWorkerLease(state, ownerId) {
+  await recoverStaleBuildWorkerLease(state);
+  return await state.transaction(async () => {
+    const lease = await state.queryOne(
+      `
+SELECT owner_pid
+FROM build_worker_lease
+WHERE id = 1
+`,
+      void 0,
+      (row) => ({
+        ownerPid: row.owner_pid === null ? void 0 : getNumber(row, "owner_pid")
+      })
+    );
+    if (lease?.ownerPid !== void 0 && isProcessAlive(lease.ownerPid)) {
+      return false;
+    }
+    await state.run(
+      `
+UPDATE build_worker_lease
+SET owner_id = ?, owner_pid = ?, heartbeat_at = ?
+WHERE id = 1
+`,
+      [ownerId, process.pid, Date.now()]
+    );
+    return true;
+  });
+}
+async function heartbeatBuildWorker(ownerId, existingState) {
+  const state = existingState ?? await openBuildQueueDatabase();
+  try {
+    await state.run(
+      `
+UPDATE build_worker_lease
+SET heartbeat_at = ?
+WHERE id = 1 AND owner_id = ?
+`,
+      [Date.now(), ownerId]
+    );
+  } finally {
+    if (existingState === void 0) {
+      await state.close();
+    }
+  }
+}
+async function releaseBuildWorkerLease(state, ownerId) {
+  await state.run(
+    `
+UPDATE build_worker_lease
+SET owner_id = NULL, owner_pid = NULL, heartbeat_at = NULL
+WHERE id = 1 AND owner_id = ?
+`,
+    [ownerId]
+  );
+}
+async function recoverStaleBuildWorkerLease(state) {
+  const lease = await state.queryOne(
+    `
+SELECT owner_id, owner_pid
+FROM build_worker_lease
+WHERE id = 1
+`,
+    void 0,
+    (row) => ({
+      ownerId: getOptionalString(row, "owner_id"),
+      ownerPid: row.owner_pid === null ? void 0 : getNumber(row, "owner_pid")
+    })
+  );
+  if (lease?.ownerPid === void 0 || isProcessAlive(lease.ownerPid)) {
+    return;
+  }
+  await state.run(
+    `
+UPDATE build_worker_lease
+SET owner_id = NULL, owner_pid = NULL, heartbeat_at = NULL
+WHERE id = 1
+`
+  );
+}
+async function requireBuildJobById(state, jobId) {
+  const job = await state.queryOne(
+    "SELECT * FROM build_jobs WHERE job_id = ?",
+    [jobId],
+    mapBuildJob
+  );
+  if (job === void 0) {
+    throw new Error(`Build job not found: ${jobId}`);
+  }
+  return job;
+}
+async function resolveBuildJobIdInState(state, jobIdPrefix) {
+  const normalizedPrefix = jobIdPrefix.trim();
+  if (normalizedPrefix === "") {
+    throw new Error("Build job id is empty.");
+  }
+  const jobs = await state.queryAll(
+    `
+SELECT job_id
+FROM build_jobs
+WHERE substr(job_id, 1, ?) = ?
+ORDER BY created_at DESC
+`,
+    [normalizedPrefix.length, normalizedPrefix],
+    (row) => getString(row, "job_id")
+  );
+  if (jobs.length === 0) {
+    throw new Error(`Build job not found: ${jobIdPrefix}`);
+  }
+  if (jobs.length > 1) {
+    throw new Error(
+      `Build job id prefix is ambiguous: ${jobIdPrefix}. Matches: ${jobs.join(
+        ", "
+      )}`
+    );
+  }
+  return jobs[0];
+}
+async function appendBuildJobEvent(job, event) {
+  const seq = await readLastBuildJobEventSeq(job) + 1;
+  const nextEvent = {
+    ...event,
+    jobId: job.jobId,
+    seq
+  };
+  await appendFile(job.eventsPath, `${JSON.stringify(nextEvent)}
+`, "utf8");
+}
+async function readLastBuildJobEventSeq(job) {
+  const events = await readBuildJobEvents(job);
+  return events.at(-1)?.seq ?? 0;
+}
+async function readMaxQueueRank(state) {
+  return await state.queryOne(
+    "SELECT COALESCE(MAX(queue_rank), 0) AS rank FROM build_jobs",
+    void 0,
+    (row) => getNumber(row, "rank")
+  ) ?? 0;
+}
+async function readMinQueueRank(state) {
+  return await state.queryOne(
+    "SELECT COALESCE(MIN(queue_rank), 0) AS rank FROM build_jobs",
+    void 0,
+    (row) => getNumber(row, "rank")
+  ) ?? 0;
+}
+async function openBuildQueueDatabase() {
+  return await openSharedStateDatabase(
+    getBuildQueueDatabasePath(),
+    BUILD_QUEUE_SCHEMA_SQL
+  );
+}
+async function openReadonlyBuildQueueDatabase() {
+  return await openBuildQueueDatabase();
+}
+function getBuildQueueDatabasePath() {
+  return join(getBuildQueueStateDirectoryPath(), "job.sqlite");
+}
+async function createJobWorkspacePath(jobId) {
+  const workspacePath = join(getBuildJobWorkspaceRootPath(), jobId);
+  await mkdir(workspacePath, { recursive: true });
+  return workspacePath;
+}
+function getBuildJobWorkspaceRootPath() {
+  return join(getBuildQueueStateDirectoryPath(), "work");
+}
+async function createJobCachePath(jobId) {
+  const cachePath = join(getBuildJobCacheRootPath(), jobId);
+  await mkdir(cachePath, { recursive: true });
+  return cachePath;
+}
+function getBuildJobCacheRootPath() {
+  return join(getBuildQueueStateDirectoryPath(), "cache");
+}
+async function createJobLogPath(jobId) {
+  const logPath = join(getBuildJobLogRootPath(), jobId);
+  await mkdir(logPath, { recursive: true });
+  return logPath;
+}
+function getBuildJobLogRootPath() {
+  return join(getBuildQueueStateDirectoryPath(), "logs");
+}
+async function createJobEventsPath(jobId) {
+  const rootPath = join(getBuildQueueStateDirectoryPath(), "events");
+  await mkdir(rootPath, { recursive: true });
+  return join(rootPath, `${jobId}.ndjson`);
+}
+function getBuildQueueStateDirectoryPath() {
+  return resolveWikiGraphJobsDirectoryPath();
+}
+function mapBuildJob(row) {
+  const currentStep = parseOptionalBuildJobTarget(
+    getOptionalString(row, "current_step"),
+    "current_step"
+  );
+  const ownerId = getOptionalString(row, "owner_id");
+  const ownerPid = row.owner_pid === null ? void 0 : getNumber(row, "owner_pid");
+  const readingSummaryStartedAt = row.reading_summary_started_at === null ? void 0 : getNumber(row, "reading_summary_started_at");
+  const finishedAt = row.finished_at === null ? void 0 : getNumber(row, "finished_at");
+  const errorJSON = getOptionalString(row, "error_json");
+  const inputRevision = row.input_revision === null ? void 0 : getNumber(row, "input_revision");
+  const llmJSON = getOptionalString(row, "llm_json");
+  const prompt = getOptionalString(row, "prompt");
+  return {
+    archiveKey: getString(row, "archive_key"),
+    archivePath: getString(row, "archive_path"),
+    cachePath: getString(row, "cache_path"),
+    chapterId: getNumber(row, "chapter_id"),
+    createdAt: getNumber(row, "created_at"),
+    ...currentStep === void 0 ? {} : { currentStep },
+    ...errorJSON === void 0 ? {} : { errorJSON },
+    eventsPath: getString(row, "events_path"),
+    ...finishedAt === void 0 ? {} : { finishedAt },
+    jobId: getString(row, "job_id"),
+    ...inputRevision === void 0 ? {} : { inputRevision },
+    logPath: getString(row, "log_path"),
+    ...llmJSON === void 0 ? {} : { llmJSON },
+    ...ownerId === void 0 ? {} : { ownerId },
+    ...ownerPid === void 0 ? {} : { ownerPid },
+    ...prompt === void 0 ? {} : { prompt },
+    queueRank: getNumber(row, "queue_rank"),
+    state: parseBuildJobState(getString(row, "state")),
+    ...readingSummaryStartedAt === void 0 ? {} : { readingSummaryStartedAt },
+    target: parseBuildJobTarget(getString(row, "target"), "target"),
+    updatedAt: getNumber(row, "updated_at"),
+    workspacePath: getString(row, "workspace_path")
+  };
+}
+function parseBuildJobState(value) {
+  if (BUILD_JOB_STATES.includes(value)) {
+    return value;
+  }
+  throw new Error(`Invalid build job state: ${value}`);
+}
+function parseBuildJobTarget(value, field) {
+  if (value === "reading-graph" || value === "knowledge-graph" || value === "reading-summary") {
+    return value;
+  }
+  throw new Error(`Invalid ${field}: ${value}`);
+}
+function parseOptionalBuildJobTarget(value, field) {
+  return value === void 0 ? void 0 : parseBuildJobTarget(value, field);
+}
+function formatBuildJobLane(target) {
+  return target === "knowledge-graph" ? "knowledge-graph" : "reading";
+}
+function getString(row, key) {
+  const value = row[key];
+  if (typeof value !== "string") {
+    throw new TypeError(`Expected ${key} to be a string`);
+  }
+  return value;
+}
+function getNumber(row, key) {
+  const value = row[key];
+  if (typeof value !== "number") {
+    throw new TypeError(`Expected ${key} to be a number`);
+  }
+  return value;
+}
+function getOptionalString(row, key) {
+  const value = row[key];
+  if (value === null || value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new TypeError(`Expected ${key} to be a string`);
+  }
+  return value;
+}
+function createArchiveKey(archivePath) {
+  return createHash("sha256").update(resolve(archivePath)).digest("hex");
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function formatErrorEvent(error) {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      name: error.name,
+      stack: error.stack
+    };
+  }
+  return error;
+}
+async function delay(ms) {
+  await new Promise((resolveDelay) => {
+    setTimeout(resolveDelay, ms);
+  });
+}
+class BuildJobProgressAccumulator {
+  #job;
+  #ownerId;
+  #outputCharactersPerToken = 4;
+  #refreshIntervalMs = 5e3;
+  #graphWords = 0;
+  #lastSnapshotAt = 0;
+  #outputCharacters = 0;
+  #phase;
+  #phaseCounters = /* @__PURE__ */ new Map();
+  #step;
+  #tokenUsage = {};
+  #readingSummaryWords = 0;
+  #stopCheckQueue = Promise.resolve();
+  #totalGraphWords = 0;
+  #totalReadingSummaryWords = 0;
+  #writeQueue = Promise.resolve();
+  constructor(job, ownerId) {
+    this.#job = job;
+    this.#ownerId = ownerId;
+  }
+  async addOutputCharacters(characters) {
+    await this.#enqueue(async () => {
+      await this.throwIfStopped();
+      this.#outputCharacters += characters;
+      await this.#snapshot();
+    });
+  }
+  async addTokenUsage(usage) {
+    await this.#enqueue(async () => {
+      await this.throwIfStopped();
+      this.#tokenUsage = {
+        ...formatOptionalTokenUsage(
+          "cacheReadTokens",
+          addOptionalNumbers(
+            this.#tokenUsage.cacheReadTokens,
+            usage.cacheReadTokens
+          )
+        ),
+        ...formatOptionalTokenUsage(
+          "inputTokens",
+          addOptionalNumbers(this.#tokenUsage.inputTokens, usage.inputTokens)
+        ),
+        ...formatOptionalTokenUsage(
+          "outputTokens",
+          addOptionalNumbers(this.#tokenUsage.outputTokens, usage.outputTokens)
+        )
+      };
+      await this.#snapshot(true);
+    });
+  }
+  async setTotals(input) {
+    await this.#enqueue(async () => {
+      await this.throwIfStopped();
+      this.#totalGraphWords = input.totalGraphWords ?? this.#totalGraphWords;
+      this.#totalReadingSummaryWords = input.totalReadingSummaryWords ?? this.#totalReadingSummaryWords;
+      await this.#snapshot(true);
+    });
+  }
+  async stepStarted(step) {
+    await this.#enqueue(async () => {
+      await this.throwIfStopped();
+      this.#step = step;
+      this.#phase = void 0;
+      this.#phaseCounters.clear();
+      await markBuildJobStep(this.#job.jobId, step);
+      await appendBuildJobEvent(this.#job, {
+        at: Date.now(),
+        jobId: this.#job.jobId,
+        seq: 0,
+        step,
+        type: "step_started"
+      });
+      await this.#snapshot(true);
+    });
+  }
+  async stepCompleted(step) {
+    await this.#enqueue(async () => {
+      await this.throwIfStopped();
+      this.#step = step;
+      this.#phase = void 0;
+      this.#phaseCounters.clear();
+      await appendBuildJobEvent(this.#job, {
+        at: Date.now(),
+        jobId: this.#job.jobId,
+        seq: 0,
+        step,
+        type: "step_completed"
+      });
+      await this.#snapshot(true);
+    });
+  }
+  async updateWords(input) {
+    await this.#enqueue(async () => {
+      await this.throwIfStopped();
+      this.#graphWords = input.graphWords === void 0 ? this.#graphWords : clampProgressWords(input.graphWords, this.#totalGraphWords);
+      this.#readingSummaryWords = input.readingSummaryWords === void 0 ? this.#readingSummaryWords : clampProgressWords(
+        input.readingSummaryWords,
+        this.#totalReadingSummaryWords
+      );
+      await this.#snapshot();
+    });
+  }
+  async updatePhase(input) {
+    await this.#enqueue(async () => {
+      await this.throwIfStopped();
+      if (this.#phase !== input.phase) {
+        this.#phaseCounters.clear();
+      }
+      this.#phase = input.phase;
+      this.#phaseCounters.set(formatProgressCounterKey(input), {
+        done: clampProgressWords(input.done, input.total),
+        name: formatProgressCounterName(input),
+        total: Math.max(0, input.total),
+        unit: input.unit
+      });
+      await this.#snapshot(input.force ?? true);
+    });
+  }
+  async throwIfStopped() {
+    const queued = this.#stopCheckQueue.then(async () => {
+      const job = await readBuildJobForStopCheck(this.#job.jobId);
+      if (job.state === "running" && job.ownerId === this.#ownerId) {
+        return;
+      }
+      throw new BuildJobStoppedError(
+        `Job ${this.#job.jobId} is ${job.state}. Stop current worker execution.`
+      );
+    });
+    this.#stopCheckQueue = queued.catch(() => void 0);
+    await queued;
+  }
+  async #enqueue(operation) {
+    const queued = this.#writeQueue.then(operation, operation);
+    this.#writeQueue = queued.catch(() => void 0);
+    await queued;
+  }
+  async #snapshot(force = false) {
+    const now = Date.now();
+    if (!force && now - this.#lastSnapshotAt < this.#refreshIntervalMs) {
+      return;
+    }
+    this.#lastSnapshotAt = now;
+    const tokens = this.#formatTokenUsage();
+    await appendBuildJobEvent(this.#job, {
+      at: now,
+      counters: this.#createCounters(),
+      jobId: this.#job.jobId,
+      ...this.#phase === void 0 ? {} : { phase: this.#phase },
+      seq: 0,
+      ...this.#step === void 0 ? {} : { step: this.#step },
+      ...tokens === void 0 ? {} : { tokens },
+      type: "status_snapshot"
+    });
+  }
+  #createCounters() {
+    const wordCounter = this.#createWordCounter();
+    return [
+      ...wordCounter === void 0 ? [] : [wordCounter],
+      ...this.#phaseCounters.values()
+    ];
+  }
+  #createWordCounter() {
+    switch (this.#step) {
+      case "reading-graph":
+        return this.#totalGraphWords <= 0 ? void 0 : {
+          done: this.#graphWords,
+          name: "words",
+          total: this.#totalGraphWords,
+          unit: "word"
+        };
+      case "reading-summary":
+        return this.#totalReadingSummaryWords <= 0 ? void 0 : {
+          done: this.#readingSummaryWords,
+          name: "words",
+          total: this.#totalReadingSummaryWords,
+          unit: "word"
+        };
+      case void 0:
+        return void 0;
+    }
+  }
+  #formatTokenUsage() {
+    const outputTokens = this.#tokenUsage.outputTokens ?? (this.#outputCharacters === 0 ? void 0 : Math.floor(this.#outputCharacters / this.#outputCharactersPerToken));
+    const usage = {
+      ...this.#tokenUsage.cacheReadTokens === void 0 ? {} : { cacheReadTokens: this.#tokenUsage.cacheReadTokens },
+      ...this.#tokenUsage.inputTokens === void 0 ? {} : { inputTokens: this.#tokenUsage.inputTokens },
+      ...outputTokens === void 0 ? {} : { outputTokens }
+    };
+    return Object.keys(usage).length === 0 ? void 0 : usage;
+  }
+}
+function formatOptionalTokenUsage(key, value) {
+  return value === void 0 ? {} : { [key]: value };
+}
+function addOptionalNumbers(left, right) {
+  if (left === void 0 && right === void 0) {
+    return void 0;
+  }
+  return (left ?? 0) + (right ?? 0);
+}
+function formatProgressCounterKey(input) {
+  return input.phaseDetail ?? input.unit;
+}
+function formatProgressCounterName(input) {
+  if (input.phaseDetail !== void 0) {
+    return input.phaseDetail;
+  }
+  switch (input.unit) {
+    case "candidate":
+      return "candidates";
+    case "char":
+      return "chars";
+    case "item":
+      return "items";
+    case "page":
+      return "page";
+    case "qid":
+      return "qids";
+    case "record":
+      return "records";
+    case "sentence":
+      return "sentences";
+    case "window":
+      return "windows";
+  }
+}
+class BuildJobStoppedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BuildJobStoppedError";
+  }
+}
+function clampProgressWords(words, totalWords) {
+  if (totalWords <= 0) {
+    return Math.max(0, words);
+  }
+  return Math.min(totalWords, Math.max(0, words));
+}
+async function markBuildJobStep(jobId, step) {
+  const state = await openBuildQueueDatabase();
+  try {
+    await state.run(
+      `
+UPDATE build_jobs
+SET current_step = ?,
+    reading_summary_started_at = CASE
+      WHEN ? = 'reading-summary' AND reading_summary_started_at IS NULL THEN ?
+      ELSE reading_summary_started_at
+    END,
+    updated_at = ?
+WHERE job_id = ?
+`,
+      [step, step, Date.now(), Date.now(), jobId]
+    );
+  } finally {
+    await state.close();
+  }
+}
+export {
+  BUILD_JOB_STATES,
+  addBuildJob,
+  assertBuildJobInputRevision,
+  assertNoActiveBuildJobConflicts,
+  assertNoActiveBuildJobs,
+  boostBuildJob,
+  cancelBuildJob,
+  cleanBuildJobs,
+  getBuildJob,
+  listBuildJobs,
+  pauseBuildJob,
+  readBuildJobEvents,
+  recordBuildJobInputRevision,
+  resolveBuildJobId,
+  resumeBuildJob,
+  runBuildJobWorker,
+  runBuildQueueGc,
+  updateBuildJobTarget
+};
+//# sourceMappingURL=build-queue.js.map