wiki-graph-core 0.3.1 → 0.4.1

package/dist/storage/wikg/wikg-coordinator/overlays.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/storage/wikg/wikg-coordinator/overlays.ts"],"sourcesContent":["import {\n  readWikgArchiveMutationToken,\n  type WikgArchiveOverlay,\n} from \"../archive/index.js\";\n\nimport { createArchiveSignature } from \"./archive-key.js\";\nimport { SEARCH_INDEX_DATABASE_ENTRY_PATH } from \"./constants.js\";\nimport { getString, mapEntryOverlay, withStateDatabase } from \"./state.js\";\nimport type { EntryOverlay } from \"./types.js\";\n\nexport async function listVisibleEntryPaths(\n  archiveEntries: readonly string[],\n  input: { readonly archiveKey: string; readonly prefix: string },\n): Promise<readonly string[]> {\n  const matchingArchiveEntries = archiveEntries.filter((entryPath) =>\n    entryPath.startsWith(input.prefix),\n  );\n  const overlays = await withStateDatabase(\n    async (state) =>\n      await state.queryAll(\n        `\nSELECT *\nFROM entry_overlays\nWHERE archive_key = ?\n`,\n        [input.archiveKey],\n        mapEntryOverlay,\n      ),\n  );\n  const entries = new Set(matchingArchiveEntries);\n\n  for (const overlay of overlays) {\n    if (!overlay.entryPath.startsWith(input.prefix)) {\n      continue;\n    }\n    if (overlay.kind === \"deleted\") {\n      entries.delete(overlay.entryPath);\n    } else {\n      entries.add(overlay.entryPath);\n    }\n  }\n\n  return [...entries].sort((left, right) => left.localeCompare(right));\n}\n\nexport async function resolveEntrySource(input: {\n  readonly archiveKey: string;\n  readonly entryPath: string;\n}): Promise<\n  | { readonly kind: \"archive\" }\n  | { readonly kind: \"deleted\" }\n  | { readonly kind: \"workspace\"; readonly path: string }\n> {\n  const overlay = await readOverlay(input.archiveKey, input.entryPath);\n\n  if (overlay?.kind === \"deleted\") {\n    return { kind: \"deleted\" };\n  }\n  if (overlay?.workspacePath !== undefined) {\n    return { kind: \"workspace\", path: overlay.workspacePath };\n  }\n  return { kind: \"archive\" };\n}\n\nexport async function readOverlay(\n  archiveKey: string,\n  entryPath: string,\n): Promise<EntryOverlay | undefined> {\n  return await withStateDatabase(\n    async (state) =>\n      await state.queryOne(\n        \"SELECT * FROM entry_overlays WHERE archive_key = ? AND entry_path = ?\",\n        [archiveKey, entryPath],\n        mapEntryOverlay,\n      ),\n  );\n}\n\nexport async function listOverlays(\n  archiveKey: string,\n): Promise<readonly EntryOverlay[]> {\n  return await withStateDatabase(\n    async (state) =>\n      await state.queryAll(\n        `\nSELECT *\nFROM entry_overlays\nWHERE archive_key = ?\nORDER BY entry_path ASC\n`,\n        [archiveKey],\n        mapEntryOverlay,\n      ),\n  );\n}\n\nexport async function upsertOverlay(input: {\n  readonly archiveKey: string;\n  readonly archivePath: string;\n  readonly entryPath: string;\n  readonly kind: \"deleted\" | \"file\";\n  readonly workspacePath?: string;\n}): Promise<void> {\n  const mutationToken =\n    input.entryPath === SEARCH_INDEX_DATABASE_ENTRY_PATH\n      ? await readWikgArchiveMutationToken(input.archivePath)\n      : undefined;\n\n  await withStateDatabase(async (state) => {\n    await state.run(\n      `\nINSERT INTO entry_overlays (\n  archive_key, archive_path, entry_path, kind, workspace_path,\n  archive_signature, mutation_token, updated_at\n) VALUES (?, ?, ?, ?, ?, ?, ?, ?)\nON CONFLICT(archive_key, entry_path)\nDO UPDATE SET kind = excluded.kind,\n              archive_path = excluded.archive_path,\n              workspace_path = excluded.workspace_path,\n              archive_signature = excluded.archive_signature,\n              mutation_token = excluded.mutation_token,\n              updated_at = excluded.updated_at\n`,\n      [\n        input.archiveKey,\n        input.archivePath,\n        input.entryPath,\n        input.kind,\n        input.workspacePath ?? null,\n        await createArchiveSignature(input.archivePath),\n        mutationToken ?? null,\n        Date.now(),\n      ],\n    );\n  });\n}\n\nexport async function deleteOverlay(\n  archiveKey: string,\n  entryPath: string,\n): Promise<void> {\n  await withStateDatabase(async (state) => {\n    await state.run(\n      \"DELETE FROM entry_overlays WHERE archive_key = ? AND entry_path = ?\",\n      [archiveKey, entryPath],\n    );\n  });\n}\n\nexport async function resolveArchivePathFromKey(\n  archiveKey: string,\n): Promise<string | undefined> {\n  return await withStateDatabase(\n    async (state) =>\n      await state.queryOne(\n        \"SELECT archive_path FROM entry_overlays WHERE archive_key = ? LIMIT 1\",\n        [archiveKey],\n        (row) => getString(row, \"archive_path\"),\n      ),\n  );\n}\n\nexport function toArchiveOverlay(overlay: EntryOverlay): WikgArchiveOverlay {\n  if (overlay.kind === \"deleted\") {\n    return {\n      entryPath: overlay.entryPath,\n      kind: \"deleted\",\n    };\n  }\n  if (overlay.workspacePath === undefined) {\n    throw new Error(`Missing workspace path for ${overlay.entryPath}.`);\n  }\n\n  return {\n    entryPath: overlay.entryPath,\n    kind: \"file\",\n    workspacePath: overlay.workspacePath,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/storage/wikg/wikg-coordinator/owners.d.ts

@@ -0,0 +1,15 @@
+declare function registerArchiveOwner(input: {
+    readonly archiveKey: string;
+    readonly ownerId: string;
+}): Promise<void>;
+declare function heartbeatArchiveOwner(input: {
+    readonly archiveKey: string;
+    readonly ownerId: string;
+}): Promise<void>;
+declare function unregisterArchiveOwner(input: {
+    readonly archiveKey: string;
+    readonly ownerId: string;
+}): Promise<void>;
+declare function reapArchive(archiveKey: string): Promise<void>;
+
+export { heartbeatArchiveOwner, reapArchive, registerArchiveOwner, unregisterArchiveOwner };

package/dist/storage/wikg/wikg-coordinator/owners.js

@@ -0,0 +1,95 @@
+import { LOCK_STALE_TIMEOUT_MS } from "./constants.js";
+import { flushArchiveOverlays } from "./flusher.js";
+import {
+  cleanupStaleState,
+  createPlaceholders,
+  getString,
+  withStateDatabase
+} from "./state.js";
+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);
+}
+export {
+  heartbeatArchiveOwner,
+  reapArchive,
+  registerArchiveOwner,
+  unregisterArchiveOwner
+};
+//# sourceMappingURL=owners.js.map

package/dist/storage/wikg/wikg-coordinator/owners.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/storage/wikg/wikg-coordinator/owners.ts"],"sourcesContent":["import { LOCK_STALE_TIMEOUT_MS } from \"./constants.js\";\nimport { flushArchiveOverlays } from \"./flusher.js\";\nimport {\n  cleanupStaleState,\n  createPlaceholders,\n  getString,\n  withStateDatabase,\n} from \"./state.js\";\n\nexport async function registerArchiveOwner(input: {\n  readonly archiveKey: string;\n  readonly ownerId: string;\n}): Promise<void> {\n  await withStateDatabase(async (state) => {\n    await cleanupStaleState(state);\n    await state.run(\n      `\nINSERT OR REPLACE INTO archive_owners (\n  archive_key, owner_id, owner_pid, heartbeat_at, created_at\n) VALUES (?, ?, ?, ?, ?)\n`,\n      [input.archiveKey, input.ownerId, process.pid, Date.now(), Date.now()],\n    );\n  });\n}\n\nexport async function heartbeatArchiveOwner(input: {\n  readonly archiveKey: string;\n  readonly ownerId: string;\n}): Promise<void> {\n  await withStateDatabase(async (state) => {\n    await state.run(\n      `\nUPDATE archive_owners\nSET heartbeat_at = ?, owner_pid = ?\nWHERE archive_key = ? AND owner_id = ?\n`,\n      [Date.now(), process.pid, input.archiveKey, input.ownerId],\n    );\n  });\n}\n\nexport async function unregisterArchiveOwner(input: {\n  readonly archiveKey: string;\n  readonly ownerId: string;\n}): Promise<void> {\n  await withStateDatabase(async (state) => {\n    await state.transaction(async () => {\n      await state.run(\n        \"DELETE FROM entry_sqlite_leases WHERE archive_key = ? AND owner_id = ?\",\n        [input.archiveKey, input.ownerId],\n      );\n      await state.run(\n        \"DELETE FROM archive_owners WHERE archive_key = ? AND owner_id = ?\",\n        [input.archiveKey, input.ownerId],\n      );\n    });\n  });\n}\n\nexport async function reapArchive(archiveKey: string): Promise<void> {\n  await withStateDatabase(async (state) => {\n    await cleanupStaleState(state);\n  });\n\n  const staleOwnerIds = await withStateDatabase(\n    async (state) =>\n      await state.queryAll(\n        `\nSELECT owner_id\nFROM archive_owners\nWHERE archive_key = ?\n  AND heartbeat_at <= ?\n`,\n        [archiveKey, Date.now() - LOCK_STALE_TIMEOUT_MS],\n        (row) => getString(row, \"owner_id\"),\n      ),\n  );\n\n  if (staleOwnerIds.length === 0) {\n    return;\n  }\n\n  await withStateDatabase(async (state) => {\n    await state.transaction(async () => {\n      await state.run(\n        `\nDELETE FROM entry_sqlite_leases\nWHERE archive_key = ?\n  AND owner_id IN (${createPlaceholders(staleOwnerIds.length)})\n`,\n        [archiveKey, ...staleOwnerIds],\n      );\n      await state.run(\n        `\nDELETE FROM archive_owners\nWHERE archive_key = ?\n  AND owner_id IN (${createPlaceholders(staleOwnerIds.length)})\n`,\n        [archiveKey, ...staleOwnerIds],\n      );\n    });\n  });\n\n  await flushArchiveOverlays(archiveKey);\n}\n"],"mappings":"AAAA,SAAS,6BAA6B;AACtC,SAAS,4BAA4B;AACrC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,eAAsB,qBAAqB,OAGzB;AAChB,QAAM,kBAAkB,OAAO,UAAU;AACvC,UAAM,kBAAkB,KAAK;AAC7B,UAAM,MAAM;AAAA,MACV;AAAA;AAAA;AAAA;AAAA;AAAA,MAKA,CAAC,MAAM,YAAY,MAAM,SAAS,QAAQ,KAAK,KAAK,IAAI,GAAG,KAAK,IAAI,CAAC;AAAA,IACvE;AAAA,EACF,CAAC;AACH;AAEA,eAAsB,sBAAsB,OAG1B;AAChB,QAAM,kBAAkB,OAAO,UAAU;AACvC,UAAM,MAAM;AAAA,MACV;AAAA;AAAA;AAAA;AAAA;AAAA,MAKA,CAAC,KAAK,IAAI,GAAG,QAAQ,KAAK,MAAM,YAAY,MAAM,OAAO;AAAA,IAC3D;AAAA,EACF,CAAC;AACH;AAEA,eAAsB,uBAAuB,OAG3B;AAChB,QAAM,kBAAkB,OAAO,UAAU;AACvC,UAAM,MAAM,YAAY,YAAY;AAClC,YAAM,MAAM;AAAA,QACV;AAAA,QACA,CAAC,MAAM,YAAY,MAAM,OAAO;AAAA,MAClC;AACA,YAAM,MAAM;AAAA,QACV;AAAA,QACA,CAAC,MAAM,YAAY,MAAM,OAAO;AAAA,MAClC;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AACH;AAEA,eAAsB,YAAY,YAAmC;AACnE,QAAM,kBAAkB,OAAO,UAAU;AACvC,UAAM,kBAAkB,KAAK;AAAA,EAC/B,CAAC;AAED,QAAM,gBAAgB,MAAM;AAAA,IAC1B,OAAO,UACL,MAAM,MAAM;AAAA,MACV;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAMA,CAAC,YAAY,KAAK,IAAI,IAAI,qBAAqB;AAAA,MAC/C,CAAC,QAAQ,UAAU,KAAK,UAAU;AAAA,IACpC;AAAA,EACJ;AAEA,MAAI,cAAc,WAAW,GAAG;AAC9B;AAAA,EACF;AAEA,QAAM,kBAAkB,OAAO,UAAU;AACvC,UAAM,MAAM,YAAY,YAAY;AAClC,YAAM,MAAM;AAAA,QACV;AAAA;AAAA;AAAA,qBAGa,mBAAmB,cAAc,MAAM,CAAC;AAAA;AAAA,QAErD,CAAC,YAAY,GAAG,aAAa;AAAA,MAC/B;AACA,YAAM,MAAM;AAAA,QACV;AAAA;AAAA;AAAA,qBAGa,mBAAmB,cAAc,MAAM,CAAC;AAAA;AAAA,QAErD,CAAC,YAAY,GAAG,aAAa;AAAA,MAC/B;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AAED,QAAM,qBAAqB,UAAU;AACvC;","names":[]}

package/dist/storage/wikg/wikg-coordinator/search-index-cache.d.ts

@@ -0,0 +1,9 @@
+import { EntryOverlay } from './types.js';
+
+declare function readSearchIndexCacheStatus(overlay: EntryOverlay): Promise<"current" | "dirty" | "missing">;
+declare function tryAdoptSearchIndexCacheOverlay(input: {
+    readonly targetArchiveKey: string;
+    readonly targetArchivePath: string;
+}): Promise<void>;
+
+export { readSearchIndexCacheStatus, tryAdoptSearchIndexCacheOverlay };

package/dist/storage/wikg/wikg-coordinator/search-index-cache.js

@@ -0,0 +1,164 @@
+import { mkdir, rename, rm } from "fs/promises";
+import { dirname } from "path";
+import { Database as DocumentDatabase } from "../../../document/index.js";
+import { ensureWikiGraphHomeSchemaCurrent } from "../../../document/home-schema-upgrade.js";
+import { readSearchIndexFingerprintFromDatabase } from "../../../retrieval/search-index/index.js";
+import { readWikgArchiveMutationToken } from "../archive/index.js";
+import { createArchiveSignature, pathExists } from "./archive-key.js";
+import {
+  hasActiveArchiveOwnerOrSqliteLease,
+  hasActiveWorkspaceUse
+} from "./activity.js";
+import { SEARCH_INDEX_DATABASE_ENTRY_PATH } from "./constants.js";
+import { acquireEntryLock } from "./locks.js";
+import { readOverlay } from "./overlays.js";
+import {
+  cleanupStaleState,
+  mapEntryOverlay,
+  withStateDatabase
+} from "./state.js";
+import { createWorkspaceFilePath } from "./workspace.js";
+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 = await readSearchIndexCacheFingerprint(
+      overlay.workspacePath
+    );
+    const currentSignature = await createArchiveSignature(overlay.archivePath);
+    if (indexedFingerprint === void 0) {
+      return "dirty";
+    }
+    return overlay.archiveSignature === currentSignature ? "current" : "dirty";
+  } catch {
+    return "dirty";
+  }
+}
+async function readSearchIndexCacheFingerprint(databasePath) {
+  await ensureWikiGraphHomeSchemaCurrent();
+  const database = await DocumentDatabase.open(databasePath, "", {
+    readonly: true
+  });
+  try {
+    return await readSearchIndexFingerprintFromDatabase(database);
+  } finally {
+    await database.close();
+  }
+}
+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
+    );
+  });
+}
+export {
+  readSearchIndexCacheStatus,
+  tryAdoptSearchIndexCacheOverlay
+};
+//# sourceMappingURL=search-index-cache.js.map

package/dist/storage/wikg/wikg-coordinator/search-index-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/storage/wikg/wikg-coordinator/search-index-cache.ts"],"sourcesContent":["import { mkdir, rename, rm } from \"fs/promises\";\nimport { dirname } from \"path\";\n\nimport { Database as DocumentDatabase } from \"../../../document/index.js\";\nimport { ensureWikiGraphHomeSchemaCurrent } from \"../../../document/home-schema-upgrade.js\";\nimport { readSearchIndexFingerprintFromDatabase } from \"../../../retrieval/search-index/index.js\";\n\nimport { readWikgArchiveMutationToken } from \"../archive/index.js\";\n\nimport { createArchiveSignature, pathExists } from \"./archive-key.js\";\nimport {\n  hasActiveArchiveOwnerOrSqliteLease,\n  hasActiveWorkspaceUse,\n} from \"./activity.js\";\nimport { SEARCH_INDEX_DATABASE_ENTRY_PATH } from \"./constants.js\";\nimport { acquireEntryLock } from \"./locks.js\";\nimport { readOverlay } from \"./overlays.js\";\nimport {\n  cleanupStaleState,\n  mapEntryOverlay,\n  withStateDatabase,\n} from \"./state.js\";\nimport type { EntryOverlay } from \"./types.js\";\nimport { createWorkspaceFilePath } from \"./workspace.js\";\n\nexport async function readSearchIndexCacheStatus(\n  overlay: EntryOverlay,\n): Promise<\"current\" | \"dirty\" | \"missing\"> {\n  if (overlay.workspacePath === undefined) {\n    return \"missing\";\n  }\n  if (!(await pathExists(overlay.workspacePath))) {\n    return \"missing\";\n  }\n  if (!(await pathExists(overlay.archivePath))) {\n    return \"dirty\";\n  }\n\n  try {\n    const indexedFingerprint = await readSearchIndexCacheFingerprint(\n      overlay.workspacePath,\n    );\n    const currentSignature = await createArchiveSignature(overlay.archivePath);\n\n    if (indexedFingerprint === undefined) {\n      return \"dirty\";\n    }\n\n    return overlay.archiveSignature === currentSignature ? \"current\" : \"dirty\";\n  } catch {\n    return \"dirty\";\n  }\n}\n\nasync function readSearchIndexCacheFingerprint(\n  databasePath: string,\n): Promise<string | undefined> {\n  await ensureWikiGraphHomeSchemaCurrent();\n  const database = await DocumentDatabase.open(databasePath, \"\", {\n    readonly: true,\n  });\n\n  try {\n    return await readSearchIndexFingerprintFromDatabase(database);\n  } finally {\n    await database.close();\n  }\n}\n\nexport async function tryAdoptSearchIndexCacheOverlay(input: {\n  readonly targetArchiveKey: string;\n  readonly targetArchivePath: string;\n}): Promise<void> {\n  const mutationToken = await readWikgArchiveMutationToken(\n    input.targetArchivePath,\n  );\n  const candidates = await listSearchIndexAdoptionCandidates({\n    mutationToken,\n    targetArchiveKey: input.targetArchiveKey,\n  });\n  const adoptable: EntryOverlay[] = [];\n\n  for (const candidate of candidates) {\n    if (\n      candidate.workspacePath === undefined ||\n      (await pathExists(candidate.archivePath)) ||\n      (await hasActiveWorkspaceUse(candidate.archiveKey))\n    ) {\n      continue;\n    }\n\n    adoptable.push(candidate);\n  }\n\n  if (adoptable.length !== 1) {\n    return;\n  }\n\n  const candidate = adoptable[0]!;\n  const releaseWriteLock = await acquireEntryLock(\n    candidate.archiveKey,\n    SEARCH_INDEX_DATABASE_ENTRY_PATH,\n    \"write\",\n  );\n\n  try {\n    const releaseStateLock = await acquireEntryLock(\n      candidate.archiveKey,\n      SEARCH_INDEX_DATABASE_ENTRY_PATH,\n      \"state\",\n    );\n\n    try {\n      const current = await readOverlay(\n        candidate.archiveKey,\n        SEARCH_INDEX_DATABASE_ENTRY_PATH,\n      );\n      const target = await readOverlay(\n        input.targetArchiveKey,\n        SEARCH_INDEX_DATABASE_ENTRY_PATH,\n      );\n\n      if (\n        current?.workspacePath === undefined ||\n        current.workspacePath !== candidate.workspacePath ||\n        current.mutationToken !== mutationToken ||\n        target !== undefined ||\n        (await pathExists(candidate.archivePath)) ||\n        (await hasActiveArchiveOwnerOrSqliteLease(\n          candidate.archiveKey,\n          SEARCH_INDEX_DATABASE_ENTRY_PATH,\n        ))\n      ) {\n        return;\n      }\n\n      const targetWorkspacePath = await createWorkspaceFilePath(\n        input.targetArchiveKey,\n        SEARCH_INDEX_DATABASE_ENTRY_PATH,\n      );\n\n      await rm(targetWorkspacePath, { force: true }).catch(() => undefined);\n      await mkdir(dirname(targetWorkspacePath), { recursive: true });\n      await rename(current.workspacePath, targetWorkspacePath);\n      await withStateDatabase(async (state) => {\n        await state.run(\n          `\nUPDATE entry_overlays\nSET archive_key = ?,\n    archive_path = ?,\n    workspace_path = ?,\n    archive_signature = ?,\n    updated_at = ?\nWHERE archive_key = ?\n  AND entry_path = ?\n`,\n          [\n            input.targetArchiveKey,\n            input.targetArchivePath,\n            targetWorkspacePath,\n            await createArchiveSignature(input.targetArchivePath),\n            Date.now(),\n            candidate.archiveKey,\n            SEARCH_INDEX_DATABASE_ENTRY_PATH,\n          ],\n        );\n      });\n    } finally {\n      await releaseStateLock();\n    }\n  } finally {\n    await releaseWriteLock();\n  }\n}\n\nasync function listSearchIndexAdoptionCandidates(input: {\n  readonly mutationToken: string;\n  readonly targetArchiveKey: string;\n}): Promise<readonly EntryOverlay[]> {\n  return await withStateDatabase(async (state) => {\n    await cleanupStaleState(state);\n    return await state.queryAll(\n      `\nSELECT *\nFROM entry_overlays\nWHERE entry_path = ?\n  AND kind = 'file'\n  AND workspace_path IS NOT NULL\n  AND mutation_token = ?\n  AND archive_key <> ?\nORDER BY updated_at ASC\n`,\n      [\n        SEARCH_INDEX_DATABASE_ENTRY_PATH,\n        input.mutationToken,\n        input.targetArchiveKey,\n      ],\n      mapEntryOverlay,\n    );\n  });\n}\n"],"mappings":"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","names":["candidate"]}

package/dist/storage/wikg/wikg-coordinator/session.d.ts

@@ -0,0 +1,43 @@
+import { DocumentFileStore } from '../../../document/directory/types.js';
+import { WorkspaceWritebackPolicy } from './types.js';
+import '../../../text/source/meta.js';
+import 'zod';
+import '../../../text/source/toc.js';
+import '../../../text/source/types.js';
+import '../../../document/database.js';
+import 'sqlite3';
+import '../../../document/types.js';
+import '../../../document/text-streams/serial.js';
+import '../../../document/text-streams/draft.js';
+import '../../../document/text-streams/types.js';
+import '../../../document/stores/chunk.js';
+import '../../../document/stores/types.js';
+import '../../../document/stores/fragment-group.js';
+import '../../../document/stores/graph-build-parameter.js';
+import '../../../document/stores/mention-link.js';
+import '../../../document/stores/mention.js';
+import '../../../document/stores/object-metadata.js';
+import '../../../document/stores/reading-edge.js';
+import '../../../document/stores/serial.js';
+import '../../../document/stores/snake/chunk.js';
+import '../../../document/stores/snake/core.js';
+import '../../../document/stores/snake/edge.js';
+
+declare class WikgArchiveSession {
+    #private;
+    constructor(archivePath: string, token?: symbol);
+    static open(archivePath: string): Promise<WikgArchiveSession>;
+    get archiveKey(): string;
+    get archivePath(): string;
+    get ownerId(): string;
+    observeDirtyEntry(entryPath: string): void;
+    modifyEntry(entryPath: string): void;
+    createFileStore(options?: {
+        readonly readonlyDatabase?: boolean;
+        readonly searchIndexWritebackPolicy?: WorkspaceWritebackPolicy;
+    }): DocumentFileStore;
+    materializeReadWorkspace<T>(directoryPath: string | undefined, operation: (documentDirectoryPath: string) => Promise<T> | T): Promise<T>;
+    close(): Promise<void>;
+}
+
+export { WikgArchiveSession };

package/dist/storage/wikg/wikg-coordinator/session.js

@@ -0,0 +1,147 @@
+import { mkdir, rm, writeFile } from "fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "path";
+import { createWikiGraphTempDirectory } from "../../../runtime/common/wiki-graph/temp.js";
+import { listWikgArchiveEntries } from "../archive/index.js";
+import { createArchiveKey, createOwnerId } from "./archive-key.js";
+import {
+  ARCHIVE_SESSION_CONSTRUCTOR_TOKEN,
+  OWNER_HEARTBEAT_INTERVAL_MS
+} from "./constants.js";
+import { WikgDocumentFileStore } from "./file-store.js";
+import { flushArchiveOverlays } from "./flusher.js";
+import {
+  heartbeatArchiveOwner,
+  reapArchive,
+  registerArchiveOwner,
+  unregisterArchiveOwner
+} from "./owners.js";
+import { listVisibleEntryPaths } from "./overlays.js";
+import { ensureEmptyDirectory } from "./workspace.js";
+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("../../../runtime/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);
+  }
+}
+export {
+  WikgArchiveSession
+};
+//# sourceMappingURL=session.js.map

package/dist/storage/wikg/wikg-coordinator/session.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/storage/wikg/wikg-coordinator/session.ts"],"sourcesContent":["import { mkdir, rm, writeFile } from \"fs/promises\";\nimport { dirname, isAbsolute, relative, resolve } from \"path\";\n\nimport { createWikiGraphTempDirectory } from \"../../../runtime/common/wiki-graph/temp.js\";\nimport type { DocumentFileStore } from \"../../../document/directory/index.js\";\n\nimport { listWikgArchiveEntries } from \"../archive/index.js\";\n\nimport { createArchiveKey, createOwnerId } from \"./archive-key.js\";\nimport {\n  ARCHIVE_SESSION_CONSTRUCTOR_TOKEN,\n  OWNER_HEARTBEAT_INTERVAL_MS,\n} from \"./constants.js\";\nimport { WikgDocumentFileStore } from \"./file-store.js\";\nimport { flushArchiveOverlays } from \"./flusher.js\";\nimport {\n  heartbeatArchiveOwner,\n  reapArchive,\n  registerArchiveOwner,\n  unregisterArchiveOwner,\n} from \"./owners.js\";\nimport { listVisibleEntryPaths } from \"./overlays.js\";\nimport type { WorkspaceWritebackPolicy } from \"./types.js\";\nimport { ensureEmptyDirectory } from \"./workspace.js\";\n\nexport class WikgArchiveSession {\n  readonly #archiveKey: string;\n  readonly #archivePath: string;\n  readonly #ownerId = createOwnerId();\n  readonly #heartbeat: NodeJS.Timeout;\n  readonly #observedDirtyEntryPaths = new Set<string>();\n  readonly #modifiedEntryPaths = new Set<string>();\n  #closed = false;\n\n  public constructor(archivePath: string, token?: symbol) {\n    if (token !== ARCHIVE_SESSION_CONSTRUCTOR_TOKEN) {\n      throw new Error(\"Use WikgCoordinator.withArchiveSession().\");\n    }\n\n    this.#archivePath = resolve(archivePath);\n    this.#archiveKey = createArchiveKey(this.#archivePath);\n    this.#heartbeat = setInterval(() => {\n      void heartbeatArchiveOwner({\n        archiveKey: this.#archiveKey,\n        ownerId: this.#ownerId,\n      }).catch(() => undefined);\n    }, OWNER_HEARTBEAT_INTERVAL_MS);\n  }\n\n  public static async open(archivePath: string): Promise<WikgArchiveSession> {\n    const session = new WikgArchiveSession(\n      archivePath,\n      ARCHIVE_SESSION_CONSTRUCTOR_TOKEN,\n    );\n\n    try {\n      await registerArchiveOwner({\n        archiveKey: session.#archiveKey,\n        ownerId: session.#ownerId,\n      });\n      return session;\n    } catch (error) {\n      clearInterval(session.#heartbeat);\n      throw error;\n    }\n  }\n\n  public get archiveKey(): string {\n    return this.#archiveKey;\n  }\n\n  public get archivePath(): string {\n    return this.#archivePath;\n  }\n\n  public get ownerId(): string {\n    return this.#ownerId;\n  }\n\n  public observeDirtyEntry(entryPath: string): void {\n    this.#observedDirtyEntryPaths.add(entryPath);\n  }\n\n  public modifyEntry(entryPath: string): void {\n    this.#modifiedEntryPaths.add(entryPath);\n  }\n\n  public createFileStore(\n    options: {\n      readonly readonlyDatabase?: boolean;\n      readonly searchIndexWritebackPolicy?: WorkspaceWritebackPolicy;\n    } = {},\n  ): DocumentFileStore {\n    return new WikgDocumentFileStore(this.#archivePath, {\n      ...options,\n      session: this,\n    });\n  }\n\n  public async materializeReadWorkspace<T>(\n    directoryPath: string | undefined,\n    operation: (documentDirectoryPath: string) => Promise<T> | T,\n  ): Promise<T> {\n    const ownsDirectoryPath = directoryPath === undefined;\n    const resolvedDirectoryPath = ownsDirectoryPath\n      ? await createWikiGraphTempDirectory(\"archive-open\")\n      : resolve(directoryPath);\n\n    if (!ownsDirectoryPath) {\n      await ensureEmptyDirectory(resolvedDirectoryPath);\n    }\n\n    const fileStore = this.createFileStore({ readonlyDatabase: true });\n    const entries = await listVisibleEntryPaths(\n      await listWikgArchiveEntries(this.#archivePath),\n      {\n        archiveKey: this.#archiveKey,\n        prefix: \"\",\n      },\n    );\n\n    try {\n      for (const entryPath of entries) {\n        const content = await fileStore.readFile(entryPath);\n\n        if (content === undefined) {\n          continue;\n        }\n\n        const targetPath = resolve(resolvedDirectoryPath, entryPath);\n        const relativeTargetPath = relative(resolvedDirectoryPath, targetPath);\n\n        if (\n          relativeTargetPath.startsWith(\"..\") ||\n          isAbsolute(relativeTargetPath)\n        ) {\n          throw new Error(`Archive entry escapes read workspace: ${entryPath}`);\n        }\n\n        await mkdir(dirname(targetPath), { recursive: true });\n        await writeFile(targetPath, content);\n      }\n\n      return await operation(resolvedDirectoryPath);\n    } finally {\n      await fileStore.close();\n      if (ownsDirectoryPath) {\n        await rm(resolvedDirectoryPath, { force: true, recursive: true });\n      }\n    }\n  }\n\n  public async close(): Promise<void> {\n    if (this.#closed) {\n      return;\n    }\n\n    this.#closed = true;\n    clearInterval(this.#heartbeat);\n\n    try {\n      await this.#settle();\n      await reapArchive(this.#archiveKey);\n    } finally {\n      await unregisterArchiveOwner({\n        archiveKey: this.#archiveKey,\n        ownerId: this.#ownerId,\n      });\n    }\n\n    await import(\"../../../runtime/gc/index.js\")\n      .then(async ({ tryRunWikiGraphGc }) => {\n        await tryRunWikiGraphGc({ opportunistic: true });\n      })\n      .catch(() => undefined);\n  }\n\n  async #settle(): Promise<void> {\n    const entryPaths = new Set([\n      ...this.#observedDirtyEntryPaths,\n      ...this.#modifiedEntryPaths,\n    ]);\n\n    if (entryPaths.size === 0) {\n      return;\n    }\n\n    await flushArchiveOverlays(this.#archiveKey, entryPaths);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/storage/wikg/wikg-coordinator/state.d.ts

@@ -0,0 +1,16 @@
+import { Database } from '../../../document/database.js';
+import { ArchiveCommitLock, EntryLock, EntryOverlay } from './types.js';
+import 'sqlite3';
+
+declare function cleanupStaleState(state: Database): Promise<void>;
+declare function createPlaceholders(count: number): string;
+declare function withStateDatabase<T>(operation: (state: Database) => Promise<T> | T): Promise<T>;
+declare function getCoordinatorStateDirectoryPath(): string;
+declare function mapEntryOverlay(row: Record<string, unknown>): EntryOverlay;
+declare function mapEntryLock(row: Record<string, unknown>): EntryLock;
+declare function mapArchiveCommitLock(row: Record<string, unknown>): ArchiveCommitLock;
+declare function getString(row: Record<string, unknown>, key: string): string;
+declare function getNumber(row: Record<string, unknown>, key: string): number;
+declare function getOptionalString(row: Record<string, unknown>, key: string): string | undefined;
+
+export { cleanupStaleState, createPlaceholders, getCoordinatorStateDirectoryPath, getNumber, getOptionalString, getString, mapArchiveCommitLock, mapEntryLock, mapEntryOverlay, withStateDatabase };