wiki-graph-core 0.3.1

package/dist/wikg/wikg-coordinator.js

@@ -0,0 +1,1687 @@
+import { createHash, randomUUID } from "crypto";
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile
+} from "fs/promises";
+import { tmpdir } from "os";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  posix,
+  relative,
+  resolve
+} from "path";
+import { resolveWikiGraphStagingDirectoryPath } from "../common/wiki-graph-dir.js";
+import { createWikiGraphTempDirectory } from "../common/wiki-graph-temp.js";
+import {
+  Database as DocumentDatabase,
+  DirectoryDocument,
+  openSharedStateDatabase
+} from "../document/index.js";
+import { createArchiveSearchIndexFingerprint } from "../archive/query/index.js";
+import { readSearchIndexFingerprintFromDatabase } from "../archive/search-index/index.js";
+import {
+  isDisposableDirectoryEntry,
+  readPathSize,
+  removeDisposableChildDirectories,
+  removeDisposableDescendantDirectories,
+  removeDisposableDirectory
+} from "../gc/files.js";
+import { AsyncSemaphore } from "../utils/async-semaphore.js";
+import { isNodeError } from "../utils/node-error.js";
+import {
+  extractWikgArchive,
+  listWikgArchiveEntries,
+  readWikgArchiveMutationToken,
+  readWikgArchiveEntry,
+  WikgArchiveReader,
+  writeWikgArchiveWithOverlays
+} from "./archive.js";
+const STATE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS entry_overlays (
+  archive_key TEXT NOT NULL,
+  archive_path TEXT NOT NULL,
+  entry_path TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  workspace_path TEXT,
+  archive_signature TEXT,
+  mutation_token TEXT,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (archive_key, entry_path)
+);
+
+CREATE TABLE IF NOT EXISTS entry_locks (
+  archive_key TEXT NOT NULL,
+  entry_path TEXT NOT NULL,
+  mode TEXT NOT NULL,
+  owner_id TEXT NOT NULL,
+  owner_pid INTEGER NOT NULL,
+  heartbeat_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (archive_key, entry_path, owner_id)
+);
+
+CREATE TABLE IF NOT EXISTS archive_owners (
+  archive_key TEXT NOT NULL,
+  owner_id TEXT NOT NULL,
+  owner_pid INTEGER NOT NULL,
+  heartbeat_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (archive_key, owner_id)
+);
+
+CREATE TABLE IF NOT EXISTS entry_sqlite_leases (
+  archive_key TEXT NOT NULL,
+  entry_path TEXT NOT NULL,
+  mode TEXT NOT NULL DEFAULT 'read',
+  owner_id TEXT NOT NULL,
+  owner_pid INTEGER NOT NULL,
+  heartbeat_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (archive_key, entry_path, owner_id)
+);
+
+CREATE TABLE IF NOT EXISTS archive_commit_locks (
+  archive_key TEXT PRIMARY KEY,
+  owner_id TEXT NOT NULL,
+  owner_pid INTEGER NOT NULL,
+  heartbeat_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL
+);
+`;
+const DATABASE_ENTRY_PATH = "database.db";
+const SEARCH_INDEX_DATABASE_ENTRY_PATH = "fts.db";
+const LOCK_POLL_INTERVAL_MS = 100;
+const LOCK_STALE_TIMEOUT_MS = 6e4;
+const OWNER_HEARTBEAT_INTERVAL_MS = 2e4;
+const SQLITE_CACHE_TTL_MS = 60 * 60 * 1e3;
+const STATE_DATABASE_SEMAPHORE = new AsyncSemaphore(1);
+const ARCHIVE_SESSION_CONSTRUCTOR_TOKEN = /* @__PURE__ */ Symbol(
+  "WikgArchiveSession constructor token"
+);
+class WikgCoordinator {
+  createFileStore(archivePath, options = {}) {
+    return new WikgDocumentFileStore(resolve(archivePath), options);
+  }
+  async withArchiveSession(archivePath, operation) {
+    const session = await WikgArchiveSession.open(resolve(archivePath));
+    try {
+      return await operation(session);
+    } finally {
+      await session.close();
+    }
+  }
+  async withReadWorkspace(archivePath, operation, options = {}) {
+    const directoryPath = options.documentDirPath === void 0 ? await createWikiGraphTempDirectory("archive-open") : resolve(options.documentDirPath);
+    try {
+      await extractWikgArchive(resolve(archivePath), directoryPath);
+      return await operation(directoryPath);
+    } finally {
+      if (options.documentDirPath === void 0) {
+        await rm(directoryPath, { force: true, recursive: true });
+      }
+    }
+  }
+  async withWriteWorkspace(archivePath, operation) {
+    const directoryPath = await createWikiGraphTempDirectory("archive-write");
+    try {
+      await extractWikgArchive(resolve(archivePath), directoryPath);
+      return await operation(directoryPath);
+    } finally {
+      await rm(directoryPath, { force: true, recursive: true });
+    }
+  }
+}
+class WikgArchiveSession {
+  #archiveKey;
+  #archivePath;
+  #ownerId = createOwnerId();
+  #heartbeat;
+  #observedDirtyEntryPaths = /* @__PURE__ */ new Set();
+  #modifiedEntryPaths = /* @__PURE__ */ new Set();
+  #closed = false;
+  constructor(archivePath, token) {
+    if (token !== ARCHIVE_SESSION_CONSTRUCTOR_TOKEN) {
+      throw new Error("Use WikgCoordinator.withArchiveSession().");
+    }
+    this.#archivePath = resolve(archivePath);
+    this.#archiveKey = createArchiveKey(this.#archivePath);
+    this.#heartbeat = setInterval(() => {
+      void heartbeatArchiveOwner({
+        archiveKey: this.#archiveKey,
+        ownerId: this.#ownerId
+      }).catch(() => void 0);
+    }, OWNER_HEARTBEAT_INTERVAL_MS);
+  }
+  static async open(archivePath) {
+    const session = new WikgArchiveSession(
+      archivePath,
+      ARCHIVE_SESSION_CONSTRUCTOR_TOKEN
+    );
+    try {
+      await registerArchiveOwner({
+        archiveKey: session.#archiveKey,
+        ownerId: session.#ownerId
+      });
+      return session;
+    } catch (error) {
+      clearInterval(session.#heartbeat);
+      throw error;
+    }
+  }
+  get archiveKey() {
+    return this.#archiveKey;
+  }
+  get archivePath() {
+    return this.#archivePath;
+  }
+  get ownerId() {
+    return this.#ownerId;
+  }
+  observeDirtyEntry(entryPath) {
+    this.#observedDirtyEntryPaths.add(entryPath);
+  }
+  modifyEntry(entryPath) {
+    this.#modifiedEntryPaths.add(entryPath);
+  }
+  createFileStore(options = {}) {
+    return new WikgDocumentFileStore(this.#archivePath, {
+      ...options,
+      session: this
+    });
+  }
+  async materializeReadWorkspace(directoryPath, operation) {
+    const ownsDirectoryPath = directoryPath === void 0;
+    const resolvedDirectoryPath = ownsDirectoryPath ? await createWikiGraphTempDirectory("archive-open") : resolve(directoryPath);
+    if (!ownsDirectoryPath) {
+      await ensureEmptyDirectory(resolvedDirectoryPath);
+    }
+    const fileStore = this.createFileStore({ readonlyDatabase: true });
+    const entries = await listVisibleEntryPaths(
+      await listWikgArchiveEntries(this.#archivePath),
+      {
+        archiveKey: this.#archiveKey,
+        prefix: ""
+      }
+    );
+    try {
+      for (const entryPath of entries) {
+        const content = await fileStore.readFile(entryPath);
+        if (content === void 0) {
+          continue;
+        }
+        const targetPath = resolve(resolvedDirectoryPath, entryPath);
+        const relativeTargetPath = relative(resolvedDirectoryPath, targetPath);
+        if (relativeTargetPath.startsWith("..") || isAbsolute(relativeTargetPath)) {
+          throw new Error(`Archive entry escapes read workspace: ${entryPath}`);
+        }
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, content);
+      }
+      return await operation(resolvedDirectoryPath);
+    } finally {
+      await fileStore.close();
+      if (ownsDirectoryPath) {
+        await rm(resolvedDirectoryPath, { force: true, recursive: true });
+      }
+    }
+  }
+  async close() {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    clearInterval(this.#heartbeat);
+    try {
+      await this.#settle();
+      await reapArchive(this.#archiveKey);
+    } finally {
+      await unregisterArchiveOwner({
+        archiveKey: this.#archiveKey,
+        ownerId: this.#ownerId
+      });
+    }
+    await import("../gc/index.js").then(async ({ tryRunWikiGraphGc }) => {
+      await tryRunWikiGraphGc({ opportunistic: true });
+    }).catch(() => void 0);
+  }
+  async #settle() {
+    const entryPaths = /* @__PURE__ */ new Set([
+      ...this.#observedDirtyEntryPaths,
+      ...this.#modifiedEntryPaths
+    ]);
+    if (entryPaths.size === 0) {
+      return;
+    }
+    await flushArchiveOverlays(this.#archiveKey, entryPaths);
+  }
+}
+async function tryStartWikgFlusher(archivePath) {
+  if (archivePath !== void 0) {
+    await flushArchiveOverlays(createArchiveKey(resolve(archivePath)));
+    return;
+  }
+  const archiveKeys = await withStateDatabase(async (state) => {
+    await cleanupStaleState(state);
+    return await state.queryAll(
+      `
+SELECT DISTINCT archive_key
+FROM entry_overlays
+ORDER BY archive_key
+`,
+      void 0,
+      (row) => getString(row, "archive_key")
+    );
+  });
+  for (const archiveKey of archiveKeys) {
+    await flushArchiveOverlays(archiveKey);
+  }
+}
+async function runWikgCoordinatorGc(context) {
+  const candidates = await listSqliteCacheGcCandidates();
+  let removed = 0;
+  let freedBytes = 0;
+  for (const candidate of candidates) {
+    const result = await tryRemoveSqliteCacheCandidate(candidate, context);
+    if (result.removed) {
+      removed += 1;
+      freedBytes += result.freedBytes;
+    }
+  }
+  const orphanedFiles = await removeOrphanedWorkspaceFiles(context);
+  const childDirectories = context.dryRun ? { freedBytes: 0, removed: 0, scanned: 0 } : await removeDisposableChildDirectories(getCoordinatorWorkspaceRootPath());
+  return {
+    freedBytes: freedBytes + orphanedFiles.freedBytes + childDirectories.freedBytes,
+    removed: removed + orphanedFiles.removed + childDirectories.removed,
+    scanned: candidates.length + orphanedFiles.scanned + childDirectories.scanned
+  };
+}
+async function listSqliteCacheGcCandidates() {
+  return await withStateDatabase(async (state) => {
+    await cleanupStaleState(state);
+    return await state.queryAll(
+      `
+SELECT overlay.*
+FROM entry_overlays AS overlay
+WHERE overlay.entry_path IN (?, ?)
+  AND overlay.kind = 'file'
+  AND overlay.workspace_path IS NOT NULL
+ORDER BY overlay.updated_at ASC
+`,
+      [DATABASE_ENTRY_PATH, SEARCH_INDEX_DATABASE_ENTRY_PATH],
+      mapEntryOverlay
+    );
+  });
+}
+async function tryRemoveSqliteCacheCandidate(candidate, context) {
+  const releaseWriteLock = await acquireEntryLock(
+    candidate.archiveKey,
+    candidate.entryPath,
+    "write"
+  );
+  try {
+    const releaseStateLock = await acquireEntryLock(
+      candidate.archiveKey,
+      candidate.entryPath,
+      "state"
+    );
+    try {
+      const overlay = await readOverlay(
+        candidate.archiveKey,
+        candidate.entryPath
+      );
+      if (overlay?.workspacePath === void 0 || overlay.workspacePath !== candidate.workspacePath || !await canRemoveSqliteCacheOverlay(overlay, context)) {
+        return { freedBytes: 0, removed: false };
+      }
+      let freedBytes = await readPathSize(overlay.workspacePath);
+      if (!context.dryRun) {
+        await deleteOverlay(overlay.archiveKey, overlay.entryPath);
+        await rm(overlay.workspacePath, { force: true });
+        freedBytes += await removeDisposableDirectory(
+          dirname(overlay.workspacePath)
+        );
+      }
+      return { freedBytes, removed: true };
+    } finally {
+      await releaseStateLock();
+    }
+  } finally {
+    await releaseWriteLock();
+  }
+}
+async function canRemoveSqliteCacheOverlay(overlay, context) {
+  if (await hasActiveArchiveOwnerOrSqliteLease(
+    overlay.archiveKey,
+    overlay.entryPath
+  )) {
+    return false;
+  }
+  if (overlay.workspacePath === void 0) {
+    return false;
+  }
+  if (await isSqliteCacheOverlayDirty(overlay)) {
+    return true;
+  }
+  if (!context.force && context.now - overlay.updatedAt < SQLITE_CACHE_TTL_MS) {
+    return false;
+  }
+  if (overlay.entryPath === SEARCH_INDEX_DATABASE_ENTRY_PATH && !context.force) {
+    return false;
+  }
+  return true;
+}
+async function isSqliteCacheOverlayDirty(overlay) {
+  if (overlay.workspacePath === void 0) {
+    return true;
+  }
+  if (!await pathExists(overlay.workspacePath)) {
+    return true;
+  }
+  if (!await pathExists(overlay.archivePath)) {
+    return true;
+  }
+  if (overlay.entryPath !== SEARCH_INDEX_DATABASE_ENTRY_PATH) {
+    return false;
+  }
+  return await readSearchIndexCacheStatus(overlay) !== "current";
+}
+async function readSearchIndexCacheStatus(overlay) {
+  if (overlay.workspacePath === void 0) {
+    return "missing";
+  }
+  if (!await pathExists(overlay.workspacePath)) {
+    return "missing";
+  }
+  if (!await pathExists(overlay.archivePath)) {
+    return "dirty";
+  }
+  try {
+    const [indexedFingerprint, currentFingerprint] = await Promise.all([
+      readSearchIndexCacheFingerprint(overlay.workspacePath),
+      createCurrentArchiveSearchIndexFingerprint(overlay.archivePath)
+    ]);
+    if (indexedFingerprint === void 0) {
+      return "dirty";
+    }
+    return indexedFingerprint === currentFingerprint ? "current" : "dirty";
+  } catch {
+    return "dirty";
+  }
+}
+async function readSearchIndexCacheFingerprint(databasePath) {
+  const database = await DocumentDatabase.open(databasePath, "", {
+    readonly: true
+  });
+  try {
+    return await readSearchIndexFingerprintFromDatabase(database);
+  } finally {
+    await database.close();
+  }
+}
+async function createCurrentArchiveSearchIndexFingerprint(archivePath) {
+  const directoryPath = await createWikiGraphTempDirectory("archive-open");
+  try {
+    await extractWikgArchive(archivePath, directoryPath);
+    const document = await DirectoryDocument.open(directoryPath);
+    try {
+      return await createArchiveSearchIndexFingerprint(document);
+    } finally {
+      await document.release();
+    }
+  } finally {
+    await rm(directoryPath, { force: true, recursive: true });
+  }
+}
+async function hasActiveArchiveOwnerOrSqliteLease(archiveKey, entryPath) {
+  return await withStateDatabase(async (state) => {
+    await cleanupStaleState(state);
+    const ownerCount = await state.queryOne(
+      "SELECT COUNT(*) AS count FROM archive_owners WHERE archive_key = ?",
+      [archiveKey],
+      (row) => getNumber(row, "count")
+    );
+    const leaseCount = await state.queryOne(
+      `
+SELECT COUNT(*) AS count
+FROM entry_sqlite_leases
+WHERE archive_key = ?
+  AND entry_path = ?
+`,
+      [archiveKey, entryPath],
+      (row) => getNumber(row, "count")
+    );
+    return (ownerCount ?? 0) > 0 || (leaseCount ?? 0) > 0;
+  });
+}
+async function hasActiveWorkspaceUse(archiveKey) {
+  return await withStateDatabase(async (state) => {
+    await cleanupStaleState(state);
+    const ownerCount = await state.queryOne(
+      "SELECT COUNT(*) AS count FROM archive_owners WHERE archive_key = ?",
+      [archiveKey],
+      (row) => getNumber(row, "count")
+    );
+    const leaseCount = await state.queryOne(
+      "SELECT COUNT(*) AS count FROM entry_sqlite_leases WHERE archive_key = ?",
+      [archiveKey],
+      (row) => getNumber(row, "count")
+    );
+    const lockCount = await state.queryOne(
+      "SELECT COUNT(*) AS count FROM entry_locks WHERE archive_key = ?",
+      [archiveKey],
+      (row) => getNumber(row, "count")
+    );
+    return (ownerCount ?? 0) > 0 || (leaseCount ?? 0) > 0 || (lockCount ?? 0) > 0;
+  });
+}
+async function removeOrphanedWorkspaceFiles(context) {
+  const rootPath = getCoordinatorWorkspaceRootPath();
+  let archiveKeyEntries;
+  try {
+    archiveKeyEntries = await readdir(rootPath, { withFileTypes: true });
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return { freedBytes: 0, removed: 0, scanned: 0 };
+    }
+    throw error;
+  }
+  let freedBytes = 0;
+  let removed = 0;
+  let scanned = 0;
+  for (const archiveKeyEntry of archiveKeyEntries) {
+    if (!archiveKeyEntry.isDirectory()) {
+      continue;
+    }
+    const archiveKey = archiveKeyEntry.name;
+    if (await hasActiveWorkspaceUse(archiveKey)) {
+      continue;
+    }
+    const referencedWorkspacePaths = new Set(
+      (await listOverlays(archiveKey)).map((overlay) => overlay.workspacePath).filter((path) => path !== void 0)
+    );
+    for (const workspacePath of await listWorkspaceFiles(
+      join(rootPath, archiveKey)
+    )) {
+      scanned += 1;
+      if (isDisposableDirectoryEntry(basename(workspacePath))) {
+        continue;
+      }
+      if (referencedWorkspacePaths.has(workspacePath)) {
+        continue;
+      }
+      const size = await readPathSize(workspacePath);
+      if (!context.dryRun) {
+        await rm(workspacePath, { force: true });
+      }
+      freedBytes += size;
+      removed += 1;
+    }
+    if (!context.dryRun) {
+      const disposableDirectories = await removeDisposableDescendantDirectories(
+        join(rootPath, archiveKey)
+      );
+      freedBytes += disposableDirectories.freedBytes;
+      removed += disposableDirectories.removed;
+      scanned += disposableDirectories.scanned;
+    }
+  }
+  return { freedBytes, removed, scanned };
+}
+class WikgDocumentFileStore {
+  #archiveKey;
+  #archivePath;
+  #archiveReader;
+  #entrySourceByPath;
+  #readonlyDatabase;
+  #searchIndexWritebackPolicy;
+  #sqliteLeaseOwnerId = createOwnerId();
+  constructor(archivePath, options) {
+    this.#archivePath = resolve(archivePath);
+    this.#archiveKey = createArchiveKey(this.#archivePath);
+    this.#readonlyDatabase = options.readonlyDatabase === true;
+    this.#searchIndexWritebackPolicy = options.searchIndexWritebackPolicy ?? "archive";
+    this.#session = options.session;
+  }
+  async #readOverlay(entryPath) {
+    const overlay = await readOverlay(this.#archiveKey, entryPath);
+    if (overlay === void 0) {
+      return void 0;
+    }
+    const signature = await createArchiveSignature(this.#archivePath);
+    if (overlay.archiveSignature === signature) {
+      return overlay;
+    }
+    await deleteOverlay(this.#archiveKey, entryPath);
+    if (overlay.workspacePath !== void 0) {
+      await rm(overlay.workspacePath, { force: true }).catch(() => void 0);
+    }
+    this.#entrySourceByPath?.delete(entryPath);
+    return void 0;
+  }
+  #session;
+  async close() {
+    if (this.#archiveReader !== void 0) {
+      (await this.#archiveReader).close();
+      this.#archiveReader = void 0;
+    }
+    await releaseSqliteLease({
+      archiveKey: this.#archiveKey,
+      entryPath: DATABASE_ENTRY_PATH,
+      ownerId: this.#sqliteLeaseOwnerId
+    });
+    await releaseSqliteLease({
+      archiveKey: this.#archiveKey,
+      entryPath: SEARCH_INDEX_DATABASE_ENTRY_PATH,
+      ownerId: this.#sqliteLeaseOwnerId
+    });
+  }
+  async deleteFile(path) {
+    const entryPath = this.#toEntryPath(path);
+    await withEntryLock(this.#archiveKey, entryPath, "write", async () => {
+      await withEntryLock(this.#archiveKey, entryPath, "state", async () => {
+        const overlay = await this.#readOverlay(entryPath);
+        await upsertOverlay({
+          archiveKey: this.#archiveKey,
+          archivePath: this.#archivePath,
+          entryPath,
+          kind: "deleted"
+        });
+        if (overlay?.workspacePath !== void 0) {
+          await rm(overlay.workspacePath, { force: true }).catch(
+            () => void 0
+          );
+        }
+        this.#entrySourceByPath?.set(entryPath, { kind: "deleted" });
+        this.#session?.modifyEntry(entryPath);
+      });
+    });
+  }
+  async deleteTree(path) {
+    const rootEntryPath = this.#toEntryPath(path);
+    const entries = await listVisibleEntryPaths(
+      await this.#listArchiveEntries(),
+      {
+        archiveKey: this.#archiveKey,
+        prefix: `${rootEntryPath}/`
+      }
+    );
+    for (const entryPath of entries) {
+      await this.deleteFile(entryPath);
+    }
+  }
+  ensureDirectory() {
+    return Promise.resolve();
+  }
+  initializeDatabaseSchema() {
+    return false;
+  }
+  markDatabaseDirty() {
+    if (!this.#readonlyDatabase) {
+      this.#session?.observeDirtyEntry(DATABASE_ENTRY_PATH);
+    }
+  }
+  markSearchIndexDatabaseDirty() {
+    if (!this.#readonlyDatabase && this.#searchIndexWritebackPolicy === "archive") {
+      this.#session?.observeDirtyEntry(SEARCH_INDEX_DATABASE_ENTRY_PATH);
+    }
+  }
+  openDatabaseReadonly() {
+    return this.#readonlyDatabase;
+  }
+  async listFiles(path) {
+    const directoryEntryPath = this.#toEntryPath(path);
+    const prefix = directoryEntryPath === "" ? "" : `${directoryEntryPath}/`;
+    const entries = (await this.#listDirectoryEntryPaths(prefix)).map(
+      ([entryPath]) => entryPath
+    );
+    return entries.map((entryPath) => entryPath.slice(prefix.length)).filter((entryPath) => !entryPath.includes("/")).map((entryPath) => posix.basename(entryPath)).sort((left, right) => left.localeCompare(right));
+  }
+  async listFileContents(path) {
+    const directoryEntryPath = this.#toEntryPath(path);
+    const prefix = directoryEntryPath === "" ? "" : `${directoryEntryPath}/`;
+    return await withEntryLock(
+      this.#archiveKey,
+      normalizeEntryDirectoryPrefix(prefix),
+      "read",
+      async () => {
+        const contents = /* @__PURE__ */ new Map();
+        for (const [entryPath, source] of await this.#listDirectoryEntryPaths(
+          prefix
+        )) {
+          const name = entryPath.slice(prefix.length);
+          if (name.includes("/")) {
+            continue;
+          }
+          if (source.kind === "workspace") {
+            contents.set(name, await readFile(source.path));
+            continue;
+          }
+          const content = await this.#readArchiveEntry(entryPath);
+          if (content !== void 0) {
+            contents.set(name, content);
+          }
+        }
+        return contents;
+      }
+    );
+  }
+  async readFile(path) {
+    const entryPath = this.#toEntryPath(path);
+    return await withEntryLock(
+      this.#archiveKey,
+      entryPath,
+      "read",
+      async () => {
+        const source = (await this.#getEntrySources()).get(entryPath) ?? await withEntryLock(
+          this.#archiveKey,
+          entryPath,
+          "state",
+          async () => await resolveEntrySource({
+            archiveKey: this.#archiveKey,
+            entryPath
+          })
+        );
+        if (source.kind === "deleted") {
+          this.#session?.observeDirtyEntry(entryPath);
+          return void 0;
+        }
+        if (source.kind === "workspace") {
+          this.#session?.observeDirtyEntry(entryPath);
+          return await readFile(source.path);
+        }
+        return await this.#readArchiveEntry(entryPath);
+      }
+    );
+  }
+  async resolveDatabasePath() {
+    return await this.#resolveSqliteDatabasePath(DATABASE_ENTRY_PATH, {
+      createIfMissing: true,
+      readonly: this.#readonlyDatabase
+    });
+  }
+  async resolveSearchIndexDatabasePath() {
+    return await this.#resolveSqliteDatabasePath(
+      SEARCH_INDEX_DATABASE_ENTRY_PATH,
+      {
+        createIfMissing: !this.#readonlyDatabase,
+        readonly: this.#readonlyDatabase
+      }
+    );
+  }
+  async #resolveSqliteDatabasePath(entryPath, options) {
+    return await withEntryLock(
+      this.#archiveKey,
+      entryPath,
+      "state",
+      async () => {
+        let overlay = await this.#readOverlay(entryPath);
+        if (entryPath === SEARCH_INDEX_DATABASE_ENTRY_PATH && overlay?.kind !== "file") {
+          await tryAdoptSearchIndexCacheOverlay({
+            targetArchiveKey: this.#archiveKey,
+            targetArchivePath: this.#archivePath
+          });
+          overlay = await this.#readOverlay(entryPath);
+        }
+        if (overlay?.kind !== "file") {
+          const content = await readWikgArchiveEntry(
+            this.#archivePath,
+            entryPath
+          );
+          if (content === void 0 && !options.createIfMissing) {
+            throw new Error(`Archive SQLite entry is missing: ${entryPath}`);
+          }
+          const workspacePath = await createWorkspaceFilePath(
+            this.#archiveKey,
+            entryPath
+          );
+          await mkdir(dirname(workspacePath), { recursive: true });
+          await writeFile(workspacePath, content ?? new Uint8Array());
+          await upsertOverlay({
+            archiveKey: this.#archiveKey,
+            archivePath: this.#archivePath,
+            entryPath,
+            kind: "file",
+            workspacePath
+          });
+          overlay = await this.#readOverlay(entryPath);
+        }
+        if (overlay?.workspacePath === void 0) {
+          throw new Error("Could not materialize SQLite database.");
+        }
+        await acquireSqliteLease({
+          archiveKey: this.#archiveKey,
+          entryPath,
+          mode: options.readonly ? "read" : "write",
+          ownerId: this.#sqliteLeaseOwnerId
+        });
+        return overlay.workspacePath;
+      }
+    );
+  }
+  async writeFile(path, content, options) {
+    const entryPath = this.#toEntryPath(path);
+    await withEntryLock(this.#archiveKey, entryPath, "write", async () => {
+      const source = await withEntryLock(
+        this.#archiveKey,
+        entryPath,
+        "state",
+        async () => await resolveEntrySource({
+          archiveKey: this.#archiveKey,
+          entryPath
+        })
+      );
+      const archiveEntryExists = source.kind === "archive" && await this.#readArchiveEntry(entryPath) !== void 0;
+      if (options.overwrite !== true && (source.kind === "workspace" || archiveEntryExists)) {
+        throw new Error(`File already exists: ${path}`);
+      }
+      await withEntryLock(this.#archiveKey, entryPath, "state", async () => {
+        const workspacePath = await createWorkspaceFilePath(
+          this.#archiveKey,
+          entryPath
+        );
+        await mkdir(dirname(workspacePath), { recursive: true });
+        const temporaryWorkspacePath = `${workspacePath}.${process.pid}.${Date.now()}.tmp`;
+        try {
+          await writeFile(temporaryWorkspacePath, content);
+          await rename(temporaryWorkspacePath, workspacePath);
+        } finally {
+          await rm(temporaryWorkspacePath, { force: true }).catch(
+            () => void 0
+          );
+        }
+        await upsertOverlay({
+          archiveKey: this.#archiveKey,
+          archivePath: this.#archivePath,
+          entryPath,
+          kind: "file",
+          workspacePath
+        });
+        this.#entrySourceByPath?.set(entryPath, {
+          kind: "workspace",
+          path: workspacePath
+        });
+        if (source.kind === "workspace" && source.path !== workspacePath) {
+          await rm(source.path, { force: true }).catch(() => void 0);
+        }
+        this.#session?.modifyEntry(entryPath);
+      });
+    });
+  }
+  #toEntryPath(path) {
+    const resolvedPath = resolve(path);
+    const rootPrefix = this.#archivePath.endsWith("/") ? this.#archivePath : `${this.#archivePath}/`;
+    if (resolvedPath.startsWith(rootPrefix)) {
+      return normalizeEntryPath(resolvedPath.slice(rootPrefix.length));
+    }
+    return normalizeEntryPath(path);
+  }
+  async #listArchiveEntries() {
+    return (await this.#getArchiveReader()).listEntries();
+  }
+  async #readArchiveEntry(entryPath) {
+    return await (await this.#getArchiveReader()).readEntry(entryPath);
+  }
+  async #getArchiveReader() {
+    this.#archiveReader ??= WikgArchiveReader.open(this.#archivePath);
+    return await this.#archiveReader;
+  }
+  async #getEntrySources() {
+    if (this.#entrySourceByPath !== void 0) {
+      return this.#entrySourceByPath;
+    }
+    const entries = /* @__PURE__ */ new Map();
+    for (const entryPath of await this.#listArchiveEntries()) {
+      entries.set(entryPath, { kind: "archive" });
+    }
+    for (const overlay of await listOverlays(this.#archiveKey)) {
+      if (overlay.kind === "deleted") {
+        entries.set(overlay.entryPath, { kind: "deleted" });
+      } else if (overlay.workspacePath !== void 0) {
+        entries.set(overlay.entryPath, {
+          kind: "workspace",
+          path: overlay.workspacePath
+        });
+      }
+    }
+    this.#entrySourceByPath = entries;
+    return entries;
+  }
+  async #listDirectoryEntryPaths(prefix) {
+    const entries = [];
+    for (const [entryPath, source] of await this.#getEntrySources()) {
+      if (source.kind === "deleted" || !entryPath.startsWith(prefix)) {
+        continue;
+      }
+      entries.push([entryPath, source]);
+    }
+    return entries.sort(([left], [right]) => left.localeCompare(right));
+  }
+}
+async function flushArchiveOverlays(archiveKey, requestedEntryPaths) {
+  const overlays = (await listOverlays(archiveKey)).filter(
+    (overlay) => requestedEntryPaths === void 0 || requestedEntryPaths.has(overlay.entryPath)
+  );
+  const archivePath = await resolveArchivePathFromKey(archiveKey);
+  if (overlays.length === 0 || archivePath === void 0) {
+    return;
+  }
+  const entryPaths = overlays.map((overlay) => overlay.entryPath).sort((left, right) => left.localeCompare(right));
+  const lockedEntryPaths = new Set(entryPaths);
+  const releaseLocks = [];
+  try {
+    for (const entryPath of entryPaths) {
+      releaseLocks.push(await acquireEntryLock(archiveKey, entryPath, "write"));
+    }
+    for (const entryPath of entryPaths) {
+      releaseLocks.push(await acquireEntryLock(archiveKey, entryPath, "state"));
+    }
+    if (entryPaths.includes(DATABASE_ENTRY_PATH)) {
+      await waitForSqliteLeasesToDrain(archiveKey, DATABASE_ENTRY_PATH);
+    }
+    if (entryPaths.includes(SEARCH_INDEX_DATABASE_ENTRY_PATH)) {
+      await waitForSqliteLeasesToDrain(
+        archiveKey,
+        SEARCH_INDEX_DATABASE_ENTRY_PATH
+      );
+    }
+    const currentOverlays = (await listOverlays(archiveKey)).filter(
+      (overlay) => lockedEntryPaths.has(overlay.entryPath)
+    );
+    if (currentOverlays.length === 0) {
+      return;
+    }
+    const releaseCommit = await acquireArchiveCommitLock(archiveKey);
+    try {
+      const temporaryDirectoryPath = await mkdtemp(
+        join(tmpdir(), "wikigraph-flush-")
+      );
+      const temporaryArchivePath = join(
+        temporaryDirectoryPath,
+        basename(archivePath)
+      );
+      try {
+        await writeWikgArchiveWithOverlays(
+          archivePath,
+          temporaryArchivePath,
+          currentOverlays.map(toArchiveOverlay)
+        );
+        await mkdir(dirname(archivePath), { recursive: true });
+        await rename(temporaryArchivePath, archivePath);
+      } finally {
+        await rm(temporaryDirectoryPath, { force: true, recursive: true });
+      }
+    } finally {
+      await releaseCommit();
+    }
+    for (const overlay of currentOverlays) {
+      await deleteOverlay(archiveKey, overlay.entryPath);
+      if (overlay.workspacePath !== void 0) {
+        await rm(overlay.workspacePath, { force: true });
+      }
+    }
+  } finally {
+    for (const release of releaseLocks.reverse()) {
+      await release();
+    }
+  }
+}
+async function acquireArchiveCommitLock(archiveKey) {
+  const ownerId = createOwnerId();
+  while (true) {
+    const acquired = await withStateDatabase(async (state) => {
+      await cleanupStaleState(state);
+      return await state.transaction(async () => {
+        const existing = await state.queryOne(
+          "SELECT * FROM archive_commit_locks WHERE archive_key = ?",
+          [archiveKey],
+          mapArchiveCommitLock
+        );
+        if (existing !== void 0) {
+          return false;
+        }
+        await state.run(
+          `
+INSERT INTO archive_commit_locks (
+  archive_key, owner_id, owner_pid, heartbeat_at, created_at
+) VALUES (?, ?, ?, ?, ?)
+`,
+          [archiveKey, ownerId, process.pid, Date.now(), Date.now()]
+        );
+        return true;
+      });
+    });
+    if (acquired) {
+      return async () => {
+        await withStateDatabase(async (releaseState) => {
+          await releaseState.run(
+            "DELETE FROM archive_commit_locks WHERE archive_key = ? AND owner_id = ?",
+            [archiveKey, ownerId]
+          );
+        });
+      };
+    }
+    await delay(LOCK_POLL_INTERVAL_MS);
+  }
+}
+async function registerArchiveOwner(input) {
+  await withStateDatabase(async (state) => {
+    await cleanupStaleState(state);
+    await state.run(
+      `
+INSERT OR REPLACE INTO archive_owners (
+  archive_key, owner_id, owner_pid, heartbeat_at, created_at
+) VALUES (?, ?, ?, ?, ?)
+`,
+      [input.archiveKey, input.ownerId, process.pid, Date.now(), Date.now()]
+    );
+  });
+}
+async function heartbeatArchiveOwner(input) {
+  await withStateDatabase(async (state) => {
+    await state.run(
+      `
+UPDATE archive_owners
+SET heartbeat_at = ?, owner_pid = ?
+WHERE archive_key = ? AND owner_id = ?
+`,
+      [Date.now(), process.pid, input.archiveKey, input.ownerId]
+    );
+  });
+}
+async function unregisterArchiveOwner(input) {
+  await withStateDatabase(async (state) => {
+    await state.transaction(async () => {
+      await state.run(
+        "DELETE FROM entry_sqlite_leases WHERE archive_key = ? AND owner_id = ?",
+        [input.archiveKey, input.ownerId]
+      );
+      await state.run(
+        "DELETE FROM archive_owners WHERE archive_key = ? AND owner_id = ?",
+        [input.archiveKey, input.ownerId]
+      );
+    });
+  });
+}
+async function reapArchive(archiveKey) {
+  await withStateDatabase(async (state) => {
+    await cleanupStaleState(state);
+  });
+  const staleOwnerIds = await withStateDatabase(
+    async (state) => await state.queryAll(
+      `
+SELECT owner_id
+FROM archive_owners
+WHERE archive_key = ?
+  AND heartbeat_at <= ?
+`,
+      [archiveKey, Date.now() - LOCK_STALE_TIMEOUT_MS],
+      (row) => getString(row, "owner_id")
+    )
+  );
+  if (staleOwnerIds.length === 0) {
+    return;
+  }
+  await withStateDatabase(async (state) => {
+    await state.transaction(async () => {
+      await state.run(
+        `
+DELETE FROM entry_sqlite_leases
+WHERE archive_key = ?
+  AND owner_id IN (${createPlaceholders(staleOwnerIds.length)})
+`,
+        [archiveKey, ...staleOwnerIds]
+      );
+      await state.run(
+        `
+DELETE FROM archive_owners
+WHERE archive_key = ?
+  AND owner_id IN (${createPlaceholders(staleOwnerIds.length)})
+`,
+        [archiveKey, ...staleOwnerIds]
+      );
+    });
+  });
+  await flushArchiveOverlays(archiveKey);
+}
+async function acquireEntryLock(archiveKey, entryPath, mode) {
+  const ownerId = createOwnerId();
+  while (true) {
+    const acquired = await withStateDatabase(async (state) => {
+      await cleanupStaleState(state);
+      return await state.transaction(async () => {
+        const conflicts = await state.queryAll(
+          `
+SELECT *
+FROM entry_locks
+WHERE archive_key = ?
+`,
+          [archiveKey],
+          mapEntryLock
+        );
+        if (conflicts.some(
+          (lock) => lock.ownerId !== ownerId && lockPathsConflict(entryPath, lock.entryPath) && locksConflict(mode, lock.mode)
+        )) {
+          return false;
+        }
+        await state.run(
+          `
+INSERT INTO entry_locks (
+  archive_key, entry_path, mode, owner_id, owner_pid, heartbeat_at, created_at
+) VALUES (?, ?, ?, ?, ?, ?, ?)
+`,
+          [
+            archiveKey,
+            entryPath,
+            mode,
+            ownerId,
+            process.pid,
+            Date.now(),
+            Date.now()
+          ]
+        );
+        return true;
+      });
+    });
+    if (acquired) {
+      return async () => {
+        await withStateDatabase(async (releaseState) => {
+          await releaseState.run(
+            `
+DELETE FROM entry_locks
+WHERE archive_key = ? AND entry_path = ? AND owner_id = ?
+`,
+            [archiveKey, entryPath, ownerId]
+          );
+        });
+      };
+    }
+    await delay(LOCK_POLL_INTERVAL_MS);
+  }
+}
+async function withEntryLock(archiveKey, entryPath, mode, operation) {
+  const release = await acquireEntryLock(archiveKey, entryPath, mode);
+  try {
+    return await operation();
+  } finally {
+    await release();
+  }
+}
+function locksConflict(requested, existing) {
+  if (requested === "state" || existing === "state") {
+    return requested === "state" && existing === "state";
+  }
+  if (requested === "read" && existing === "read") {
+    return false;
+  }
+  return true;
+}
+function lockPathsConflict(requested, existing) {
+  return requested === existing || lockPathContains(requested, existing) || lockPathContains(existing, requested);
+}
+function lockPathContains(parent, child) {
+  return parent.endsWith("/") && child.startsWith(parent);
+}
+async function acquireSqliteLease(input) {
+  await withStateDatabase(async (state) => {
+    await cleanupStaleState(state);
+    await state.run(
+      `
+INSERT OR REPLACE INTO entry_sqlite_leases (
+  archive_key, entry_path, mode, owner_id, owner_pid, heartbeat_at, created_at
+) VALUES (?, ?, ?, ?, ?, ?, ?)
+`,
+      [
+        input.archiveKey,
+        input.entryPath,
+        input.mode,
+        input.ownerId,
+        process.pid,
+        Date.now(),
+        Date.now()
+      ]
+    );
+  });
+}
+async function releaseSqliteLease(input) {
+  await withStateDatabase(async (state) => {
+    await state.run(
+      `
+DELETE FROM entry_sqlite_leases
+WHERE archive_key = ? AND entry_path = ? AND owner_id = ?
+`,
+      [input.archiveKey, input.entryPath, input.ownerId]
+    );
+  });
+}
+async function waitForSqliteLeasesToDrain(archiveKey, entryPath) {
+  while (true) {
+    const count = await withStateDatabase(async (state) => {
+      await cleanupStaleState(state);
+      return await state.queryOne(
+        `
+SELECT COUNT(*) AS count
+FROM entry_sqlite_leases AS lease
+LEFT JOIN archive_owners AS owner
+  ON owner.archive_key = lease.archive_key
+ AND owner.owner_id = lease.owner_id
+WHERE lease.archive_key = ?
+  AND lease.entry_path = ?
+  AND (
+    owner.owner_id IS NULL
+    OR owner.heartbeat_at > ?
+  )
+`,
+        [archiveKey, entryPath, Date.now() - LOCK_STALE_TIMEOUT_MS],
+        (row) => getNumber(row, "count")
+      );
+    });
+    if (count === 0) {
+      return;
+    }
+    await delay(LOCK_POLL_INTERVAL_MS);
+  }
+}
+async function listVisibleEntryPaths(archiveEntries, input) {
+  const matchingArchiveEntries = archiveEntries.filter(
+    (entryPath) => entryPath.startsWith(input.prefix)
+  );
+  const overlays = await withStateDatabase(
+    async (state) => await state.queryAll(
+      `
+SELECT *
+FROM entry_overlays
+WHERE archive_key = ?
+`,
+      [input.archiveKey],
+      mapEntryOverlay
+    )
+  );
+  const entries = new Set(matchingArchiveEntries);
+  for (const overlay of overlays) {
+    if (!overlay.entryPath.startsWith(input.prefix)) {
+      continue;
+    }
+    if (overlay.kind === "deleted") {
+      entries.delete(overlay.entryPath);
+    } else {
+      entries.add(overlay.entryPath);
+    }
+  }
+  return [...entries].sort((left, right) => left.localeCompare(right));
+}
+async function resolveEntrySource(input) {
+  const overlay = await readOverlay(input.archiveKey, input.entryPath);
+  if (overlay?.kind === "deleted") {
+    return { kind: "deleted" };
+  }
+  if (overlay?.workspacePath !== void 0) {
+    return { kind: "workspace", path: overlay.workspacePath };
+  }
+  return { kind: "archive" };
+}
+async function readOverlay(archiveKey, entryPath) {
+  return await withStateDatabase(
+    async (state) => await state.queryOne(
+      "SELECT * FROM entry_overlays WHERE archive_key = ? AND entry_path = ?",
+      [archiveKey, entryPath],
+      mapEntryOverlay
+    )
+  );
+}
+async function listOverlays(archiveKey) {
+  return await withStateDatabase(
+    async (state) => await state.queryAll(
+      `
+SELECT *
+FROM entry_overlays
+WHERE archive_key = ?
+ORDER BY entry_path ASC
+`,
+      [archiveKey],
+      mapEntryOverlay
+    )
+  );
+}
+async function upsertOverlay(input) {
+  const mutationToken = input.entryPath === SEARCH_INDEX_DATABASE_ENTRY_PATH ? await readWikgArchiveMutationToken(input.archivePath) : void 0;
+  await withStateDatabase(async (state) => {
+    await state.run(
+      `
+INSERT INTO entry_overlays (
+  archive_key, archive_path, entry_path, kind, workspace_path,
+  archive_signature, mutation_token, updated_at
+) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(archive_key, entry_path)
+DO UPDATE SET kind = excluded.kind,
+              archive_path = excluded.archive_path,
+              workspace_path = excluded.workspace_path,
+              archive_signature = excluded.archive_signature,
+              mutation_token = excluded.mutation_token,
+              updated_at = excluded.updated_at
+`,
+      [
+        input.archiveKey,
+        input.archivePath,
+        input.entryPath,
+        input.kind,
+        input.workspacePath ?? null,
+        await createArchiveSignature(input.archivePath),
+        mutationToken ?? null,
+        Date.now()
+      ]
+    );
+  });
+}
+async function tryAdoptSearchIndexCacheOverlay(input) {
+  const mutationToken = await readWikgArchiveMutationToken(
+    input.targetArchivePath
+  );
+  const candidates = await listSearchIndexAdoptionCandidates({
+    mutationToken,
+    targetArchiveKey: input.targetArchiveKey
+  });
+  const adoptable = [];
+  for (const candidate2 of candidates) {
+    if (candidate2.workspacePath === void 0 || await pathExists(candidate2.archivePath) || await hasActiveWorkspaceUse(candidate2.archiveKey)) {
+      continue;
+    }
+    adoptable.push(candidate2);
+  }
+  if (adoptable.length !== 1) {
+    return;
+  }
+  const candidate = adoptable[0];
+  const releaseWriteLock = await acquireEntryLock(
+    candidate.archiveKey,
+    SEARCH_INDEX_DATABASE_ENTRY_PATH,
+    "write"
+  );
+  try {
+    const releaseStateLock = await acquireEntryLock(
+      candidate.archiveKey,
+      SEARCH_INDEX_DATABASE_ENTRY_PATH,
+      "state"
+    );
+    try {
+      const current = await readOverlay(
+        candidate.archiveKey,
+        SEARCH_INDEX_DATABASE_ENTRY_PATH
+      );
+      const target = await readOverlay(
+        input.targetArchiveKey,
+        SEARCH_INDEX_DATABASE_ENTRY_PATH
+      );
+      if (current?.workspacePath === void 0 || current.workspacePath !== candidate.workspacePath || current.mutationToken !== mutationToken || target !== void 0 || await pathExists(candidate.archivePath) || await hasActiveArchiveOwnerOrSqliteLease(
+        candidate.archiveKey,
+        SEARCH_INDEX_DATABASE_ENTRY_PATH
+      )) {
+        return;
+      }
+      const targetWorkspacePath = await createWorkspaceFilePath(
+        input.targetArchiveKey,
+        SEARCH_INDEX_DATABASE_ENTRY_PATH
+      );
+      await rm(targetWorkspacePath, { force: true }).catch(() => void 0);
+      await mkdir(dirname(targetWorkspacePath), { recursive: true });
+      await rename(current.workspacePath, targetWorkspacePath);
+      await withStateDatabase(async (state) => {
+        await state.run(
+          `
+UPDATE entry_overlays
+SET archive_key = ?,
+    archive_path = ?,
+    workspace_path = ?,
+    archive_signature = ?,
+    updated_at = ?
+WHERE archive_key = ?
+  AND entry_path = ?
+`,
+          [
+            input.targetArchiveKey,
+            input.targetArchivePath,
+            targetWorkspacePath,
+            await createArchiveSignature(input.targetArchivePath),
+            Date.now(),
+            candidate.archiveKey,
+            SEARCH_INDEX_DATABASE_ENTRY_PATH
+          ]
+        );
+      });
+    } finally {
+      await releaseStateLock();
+    }
+  } finally {
+    await releaseWriteLock();
+  }
+}
+async function listSearchIndexAdoptionCandidates(input) {
+  return await withStateDatabase(async (state) => {
+    await cleanupStaleState(state);
+    return await state.queryAll(
+      `
+SELECT *
+FROM entry_overlays
+WHERE entry_path = ?
+  AND kind = 'file'
+  AND workspace_path IS NOT NULL
+  AND mutation_token = ?
+  AND archive_key <> ?
+ORDER BY updated_at ASC
+`,
+      [
+        SEARCH_INDEX_DATABASE_ENTRY_PATH,
+        input.mutationToken,
+        input.targetArchiveKey
+      ],
+      mapEntryOverlay
+    );
+  });
+}
+async function deleteOverlay(archiveKey, entryPath) {
+  await withStateDatabase(async (state) => {
+    await state.run(
+      "DELETE FROM entry_overlays WHERE archive_key = ? AND entry_path = ?",
+      [archiveKey, entryPath]
+    );
+  });
+}
+async function resolveArchivePathFromKey(archiveKey) {
+  return await withStateDatabase(
+    async (state) => await state.queryOne(
+      "SELECT archive_path FROM entry_overlays WHERE archive_key = ? LIMIT 1",
+      [archiveKey],
+      (row) => getString(row, "archive_path")
+    )
+  );
+}
+async function cleanupStaleState(state) {
+  const now = Date.now();
+  const staleOwnerPids = /* @__PURE__ */ new Set();
+  for (const tableName of [
+    "archive_owners",
+    "entry_locks",
+    "entry_sqlite_leases",
+    "archive_commit_locks"
+  ]) {
+    const rows = await state.queryAll(
+      `
+SELECT DISTINCT owner_pid
+FROM ${tableName}
+WHERE owner_pid IS NOT NULL
+  AND heartbeat_at <= ?
+`,
+      [now - LOCK_STALE_TIMEOUT_MS],
+      (row) => getNumber(row, "owner_pid")
+    );
+    for (const ownerPid of rows) {
+      if (!isProcessAlive(ownerPid)) {
+        staleOwnerPids.add(ownerPid);
+      }
+    }
+  }
+  if (staleOwnerPids.size === 0) {
+    return;
+  }
+  await state.run(
+    `
+DELETE FROM archive_owners
+WHERE owner_pid IN (${createPlaceholders(staleOwnerPids.size)})
+`,
+    [...staleOwnerPids]
+  );
+  await state.run(
+    `
+DELETE FROM entry_locks
+WHERE owner_pid IN (${createPlaceholders(staleOwnerPids.size)})
+`,
+    [...staleOwnerPids]
+  );
+  await state.run(
+    `
+DELETE FROM entry_sqlite_leases
+WHERE owner_pid IN (${createPlaceholders(staleOwnerPids.size)})
+`,
+    [...staleOwnerPids]
+  );
+  await state.run(
+    `
+DELETE FROM archive_commit_locks
+WHERE owner_pid IN (${createPlaceholders(staleOwnerPids.size)})
+`,
+    [...staleOwnerPids]
+  );
+}
+function createPlaceholders(count) {
+  return Array.from({ length: count }, () => "?").join(", ");
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+      return false;
+    }
+    return true;
+  }
+}
+async function withStateDatabase(operation) {
+  return await STATE_DATABASE_SEMAPHORE.use(async () => {
+    const state = await openStateDatabase();
+    try {
+      return await operation(state);
+    } finally {
+      await state.close();
+    }
+  });
+}
+async function openStateDatabase() {
+  const database = await openSharedStateDatabase(
+    join(getCoordinatorStateDirectoryPath(), "staging.sqlite"),
+    STATE_SCHEMA_SQL
+  );
+  await migrateStateDatabase(database);
+  return database;
+}
+async function migrateStateDatabase(database) {
+  const overlayColumns = await database.queryAll(
+    "PRAGMA table_info(entry_overlays)",
+    void 0,
+    (row) => getString(row, "name")
+  );
+  if (!overlayColumns.includes("archive_signature")) {
+    await database.run(`
+      ALTER TABLE entry_overlays
+      ADD COLUMN archive_signature TEXT
+    `);
+  }
+  if (!overlayColumns.includes("mutation_token")) {
+    await database.run(`
+      ALTER TABLE entry_overlays
+      ADD COLUMN mutation_token TEXT
+    `);
+  }
+  const sqliteLeaseColumns = await database.queryAll(
+    "PRAGMA table_info(entry_sqlite_leases)",
+    void 0,
+    (row) => getString(row, "name")
+  );
+  if (!sqliteLeaseColumns.includes("mode")) {
+    await database.run(`
+      ALTER TABLE entry_sqlite_leases
+      ADD COLUMN mode TEXT NOT NULL DEFAULT 'read'
+    `);
+  }
+}
+async function createWorkspaceFilePath(archiveKey, entryPath) {
+  const directoryPath = join(
+    getCoordinatorWorkspaceRootPath(),
+    archiveKey,
+    dirname(entryPath)
+  );
+  await mkdir(directoryPath, { recursive: true });
+  return join(directoryPath, basename(entryPath));
+}
+function getCoordinatorWorkspaceRootPath() {
+  return join(getCoordinatorStateDirectoryPath(), "work");
+}
+async function ensureEmptyDirectory(directoryPath) {
+  await mkdir(directoryPath, { recursive: true });
+  const entries = await readdir(directoryPath);
+  if (entries.length > 0) {
+    throw new Error(`Read workspace directory is not empty: ${directoryPath}`);
+  }
+}
+async function listWorkspaceFiles(directoryPath) {
+  let entries;
+  try {
+    entries = await readdir(directoryPath, { withFileTypes: true });
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const files = [];
+  for (const entry of entries) {
+    const path = join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listWorkspaceFiles(path));
+    } else if (entry.isFile()) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+function toArchiveOverlay(overlay) {
+  if (overlay.kind === "deleted") {
+    return {
+      entryPath: overlay.entryPath,
+      kind: "deleted"
+    };
+  }
+  if (overlay.workspacePath === void 0) {
+    throw new Error(`Missing workspace path for ${overlay.entryPath}.`);
+  }
+  return {
+    entryPath: overlay.entryPath,
+    kind: "file",
+    workspacePath: overlay.workspacePath
+  };
+}
+function normalizeEntryPath(path) {
+  return path.replaceAll("\\", "/").replace(/^\/+/u, "");
+}
+function normalizeEntryDirectoryPrefix(path) {
+  const entryPath = normalizeEntryPath(path);
+  return entryPath === "" || entryPath.endsWith("/") ? entryPath : `${entryPath}/`;
+}
+function getCoordinatorStateDirectoryPath() {
+  return resolveWikiGraphStagingDirectoryPath();
+}
+function createArchiveKey(archivePath) {
+  return createHash("sha256").update(resolve(archivePath)).digest("hex");
+}
+async function createArchiveSignature(archivePath) {
+  const stats = await stat(archivePath);
+  return `${stats.size}:${stats.mtimeMs}`;
+}
+function createOwnerId() {
+  return `${process.pid}-${randomUUID()}`;
+}
+async function delay(ms) {
+  await new Promise((resolveDelay) => {
+    setTimeout(resolveDelay, ms);
+  });
+}
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+function mapEntryOverlay(row) {
+  const workspacePath = getOptionalString(row, "workspace_path");
+  const archiveSignature = getOptionalString(row, "archive_signature");
+  const mutationToken = getOptionalString(row, "mutation_token");
+  return {
+    archiveKey: getString(row, "archive_key"),
+    archivePath: getString(row, "archive_path"),
+    ...archiveSignature === void 0 ? {} : { archiveSignature },
+    entryPath: getString(row, "entry_path"),
+    kind: getOverlayKind(row),
+    ...mutationToken === void 0 ? {} : { mutationToken },
+    updatedAt: getNumber(row, "updated_at"),
+    ...workspacePath === void 0 ? {} : { workspacePath }
+  };
+}
+function mapEntryLock(row) {
+  return {
+    entryPath: getString(row, "entry_path"),
+    mode: getEntryLockMode(row),
+    ownerId: getString(row, "owner_id")
+  };
+}
+function mapArchiveCommitLock(row) {
+  return {
+    ownerId: getString(row, "owner_id")
+  };
+}
+function getEntryLockMode(row) {
+  const mode = getString(row, "mode");
+  if (mode === "read" || mode === "state" || mode === "write") {
+    return mode;
+  }
+  throw new Error(`Unsupported entry lock mode: ${mode}.`);
+}
+function getOverlayKind(row) {
+  const kind = getString(row, "kind");
+  if (kind === "deleted" || kind === "file") {
+    return kind;
+  }
+  throw new Error(`Unsupported entry overlay kind: ${kind}.`);
+}
+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;
+}
+export {
+  WikgArchiveSession,
+  WikgCoordinator,
+  runWikgCoordinatorGc,
+  tryStartWikgFlusher
+};
+//# sourceMappingURL=wikg-coordinator.js.map