pi-obsidian-memory 0.0.1 → 0.1.0

package/src/services/search-index/constants.ts

@@ -0,0 +1,102 @@
+import { Compile } from "typebox/compile"
+
+import { CatalogEntrySchema, CatalogNoteSchema } from "#src/domain"
+import { CatalogRowSchema } from "./schemas.ts"
+
+export const CATALOG_VALIDATION_POLICY = "vault-note-analysis-v1"
+
+export const INDEX_FILE_EXTENSION = ".sqlite"
+
+export const INDEX_FILE_NAME_LENGTH = 16
+
+export const STATEMENT_WEIGHT = 2
+
+export const BODY_WEIGHT = 1
+
+export const WORD_PATTERN = /[\p{L}\p{N}]+/gu
+
+export const INDEX_SCHEMA_VERSION = 3
+
+export const CatalogRowValidator = Compile(CatalogRowSchema)
+
+export const CatalogEntryValidator = Compile(CatalogEntrySchema)
+
+export const CatalogNoteValidator = Compile(CatalogNoteSchema)
+
+export const SQLITE_PRIMARY_CODE_MASK = 0xff
+
+export const SQLITE_ERROR = 1
+
+export const SQLITE_CORRUPT = 11
+
+export const SQLITE_NOTADB = 26
+
+export const REBUILD_SCHEMA_SQL = `
+  DROP TABLE IF EXISTS notes_fts;
+  DROP TABLE IF EXISTS notes;
+  DROP TABLE IF EXISTS catalog_state;
+  DROP TABLE IF EXISTS vector_chunks;
+  DROP TABLE IF EXISTS vector_generation;
+  DROP TABLE IF EXISTS folder_indexes;
+  CREATE TABLE catalog_state (
+    singleton INTEGER PRIMARY KEY CHECK(singleton = 1),
+    revision INTEGER NOT NULL,
+    population TEXT NOT NULL
+  );
+  INSERT INTO catalog_state VALUES (1, 0, 'needs-population');
+  CREATE TABLE folder_indexes (
+    folder TEXT PRIMARY KEY,
+    fingerprint TEXT NOT NULL,
+    index_size INTEGER NOT NULL,
+    index_mtime_ms REAL NOT NULL,
+    index_ctime_ms REAL NOT NULL,
+    index_ino TEXT NOT NULL
+  );
+  CREATE TABLE vector_generation (
+    singleton INTEGER PRIMARY KEY CHECK(singleton = 1),
+    fingerprint TEXT NOT NULL,
+    dimensions INTEGER NOT NULL
+  );
+  CREATE TABLE vector_chunks (
+    content_fingerprint TEXT NOT NULL,
+    chunk INTEGER NOT NULL,
+    vector TEXT NOT NULL,
+    PRIMARY KEY(content_fingerprint, chunk)
+  );
+  CREATE TABLE notes (
+    rowid INTEGER PRIMARY KEY,
+    path TEXT NOT NULL UNIQUE,
+    id TEXT,
+    folder TEXT NOT NULL,
+    statement TEXT,
+    body TEXT,
+    type TEXT,
+    dont_forget INTEGER,
+    archived INTEGER,
+    size INTEGER NOT NULL,
+    modified_ms REAL NOT NULL,
+    hash TEXT NOT NULL,
+    content_fingerprint TEXT,
+    validation_fingerprint TEXT NOT NULL,
+    needs_fixing INTEGER NOT NULL
+  );
+  CREATE INDEX notes_id ON notes(id);
+  CREATE VIRTUAL TABLE notes_fts USING fts5(
+    statement, body,
+    content = 'notes', content_rowid = 'rowid',
+    tokenize = 'porter unicode61'
+  );
+  CREATE TRIGGER notes_insert AFTER INSERT ON notes BEGIN
+    INSERT INTO notes_fts(rowid, statement, body) VALUES (new.rowid, new.statement, new.body);
+  END;
+  CREATE TRIGGER notes_delete AFTER DELETE ON notes BEGIN
+    INSERT INTO notes_fts(notes_fts, rowid, statement, body)
+      VALUES ('delete', old.rowid, old.statement, old.body);
+  END;
+  CREATE TRIGGER notes_update AFTER UPDATE OF statement, body ON notes BEGIN
+    INSERT INTO notes_fts(notes_fts, rowid, statement, body)
+      VALUES ('delete', old.rowid, old.statement, old.body);
+    INSERT INTO notes_fts(rowid, statement, body) VALUES (new.rowid, new.statement, new.body);
+  END;
+  PRAGMA user_version = ${INDEX_SCHEMA_VERSION};
+`

package/src/services/search-index/dont-forget.ts

@@ -0,0 +1 @@
+export { dontForgetCandidates } from "#src/domain"

package/src/services/search-index/fingerprint.ts

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto"
+
+import type { MemoryConfig } from "#src/domain"
+import { CATALOG_VALIDATION_POLICY } from "./constants.ts"
+
+export function catalogValidationFingerprint(limits: MemoryConfig["limits"]): string {
+  return createHash("sha256")
+    .update(
+      JSON.stringify([
+        CATALOG_VALIDATION_POLICY,
+        limits.maxStatementChars,
+        limits.maxBodyChars,
+        limits.maxNotesPerFolder,
+      ]),
+    )
+    .digest("hex")
+}

package/src/services/search-index/folder-index-statements.ts

@@ -0,0 +1,17 @@
+import type { DatabaseSync } from "node:sqlite"
+
+export function prepareFolderIndexStatements(database: DatabaseSync) {
+  return {
+    all: database.prepare(
+      "SELECT folder, fingerprint, index_size, index_mtime_ms, index_ctime_ms, index_ino FROM folder_indexes ORDER BY folder",
+    ),
+    put: database.prepare(`
+      INSERT INTO folder_indexes (folder, fingerprint, index_size, index_mtime_ms, index_ctime_ms, index_ino)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(folder) DO UPDATE SET fingerprint = excluded.fingerprint,
+        index_size = excluded.index_size, index_mtime_ms = excluded.index_mtime_ms,
+        index_ctime_ms = excluded.index_ctime_ms, index_ino = excluded.index_ino
+    `),
+    prune: database.prepare("DELETE FROM folder_indexes WHERE folder NOT IN (SELECT value FROM json_each(?))"),
+  }
+}

package/src/services/search-index/folder-index-storage.ts

@@ -0,0 +1,54 @@
+import { Value } from "typebox/value"
+
+import type { prepareFolderIndexStatements } from "./folder-index-statements.ts"
+import { corruptCatalog } from "./inventory.ts"
+import { invalidCatalog } from "./reconcile.ts"
+import { FolderIndexRowSchema, FolderIndexWriteSchema } from "./schemas.ts"
+import type { FolderIndexState, FolderIndexStatesResult, IndexWriteResult } from "./types.ts"
+
+export function readStoredFolderIndexes(
+  statements: ReturnType<typeof prepareFolderIndexStatements>,
+): FolderIndexStatesResult {
+  const states: FolderIndexState[] = []
+  for (const row of statements.all.all()) {
+    if (
+      !Value.Check(FolderIndexRowSchema, row) ||
+      !Number.isFinite(row.index_mtime_ms) ||
+      !Number.isFinite(row.index_ctime_ms)
+    )
+      return corruptCatalog()
+    states.push({
+      folder: row.folder,
+      fingerprint: row.fingerprint,
+      indexSize: row.index_size,
+      indexMtimeMs: row.index_mtime_ms,
+      indexCtimeMs: row.index_ctime_ms,
+      indexIno: row.index_ino,
+    })
+  }
+  return { succeeded: true, output: states }
+}
+
+export function writeFolderIndexStates(
+  statements: ReturnType<typeof prepareFolderIndexStatements>,
+  states: FolderIndexState[],
+  keepFolders: string[],
+): IndexWriteResult {
+  const valid =
+    Value.Check(FolderIndexWriteSchema, { states, keepFolders }) &&
+    states.every((state) => Number.isFinite(state.indexMtimeMs) && Number.isFinite(state.indexCtimeMs))
+  if (!valid) return invalidCatalog("the folder index states are invalid")
+
+  for (const state of states) {
+    statements.put.run(
+      state.folder,
+      state.fingerprint,
+      state.indexSize,
+      state.indexMtimeMs,
+      state.indexCtimeMs,
+      state.indexIno,
+    )
+  }
+  statements.prune.run(JSON.stringify(keepFolders))
+  return { succeeded: true }
+}

package/src/services/search-index/folder-indexes.ts

@@ -0,0 +1,13 @@
+import type { FolderIndexState, FolderIndexStatesResult, IndexWriteResult, SearchIndex } from "./types.ts"
+
+export function readFolderIndexStates(index: SearchIndex): FolderIndexStatesResult {
+  return index.folderIndexes()
+}
+
+export function recordFolderIndexStates(
+  index: SearchIndex,
+  states: FolderIndexState[],
+  keepFolders: string[],
+): IndexWriteResult {
+  return index.recordFolderIndexes(states, keepFolders)
+}

package/src/services/search-index/index.ts

@@ -0,0 +1,14 @@
+export * from "./catalog.ts"
+export * from "./close.ts"
+export * from "./dont-forget.ts"
+export * from "./fingerprint.ts"
+export * from "./folder-indexes.ts"
+export * from "./inspection.ts"
+export * from "./location.ts"
+export * from "./open.ts"
+export * from "./ranking.ts"
+export * from "./recovery.ts"
+export * from "./search.ts"
+export * from "./types.ts"
+export * from "./vectors.ts"
+export * from "./write.ts"

package/src/services/search-index/inspection.ts

@@ -0,0 +1 @@
+export { classifyAliasFailure, inspectedCatalogEntry, reusableCatalogEntry } from "#src/domain"

package/src/services/search-index/inventory.ts

@@ -0,0 +1,67 @@
+import { Value } from "typebox/value"
+
+import type { CatalogEntry } from "#src/domain"
+import type { prepareCatalogStatements } from "./catalog-statements.ts"
+import { CatalogEntryValidator, CatalogNoteValidator, CatalogRowValidator } from "./constants.ts"
+import { CatalogStateSchema } from "./schemas.ts"
+import type { CatalogRow, InventoryResult, SearchIndexRefusal } from "./types.ts"
+
+export function readInventory(statements: ReturnType<typeof prepareCatalogStatements>): InventoryResult {
+  const state = statements.state.get()
+  if (!Value.Check(CatalogStateSchema, state)) return corruptCatalog()
+
+  const entries: CatalogEntry[] = []
+  for (const row of statements.inventory.all()) {
+    if (!CatalogRowValidator.Check(row)) return corruptCatalog()
+    const entry = entryFromRow(row)
+    if (!entry || !validCatalogEntry(entry)) return corruptCatalog()
+    entries.push(entry)
+  }
+  return { succeeded: true, output: { ...state, entries } }
+}
+
+export function validCatalogEntry(entry: CatalogEntry): boolean {
+  if (!CatalogEntryValidator.Check(entry) || !Number.isFinite(entry.stat.mtimeMs)) return false
+  if (!entry.note) return !entry.contentFingerprint && entry.needsFixing
+  if (!entry.contentFingerprint) return false
+  return entry.note.archived || entry.path.split("/")[0]?.toLowerCase() !== "archive"
+}
+
+function entryFromRow(row: CatalogRow): CatalogEntry | null {
+  const entry: CatalogEntry = {
+    path: row.path,
+    stat: { size: row.size, mtimeMs: row.modified_ms },
+    rawHash: row.hash,
+    contentFingerprint: row.content_fingerprint,
+    validationFingerprint: row.validation_fingerprint,
+    needsFixing: row.needs_fixing === 1,
+    note: null,
+  }
+  if (!row.id) {
+    const columns = [row.type, row.statement, row.body, row.dont_forget, row.archived]
+    if (columns.some((value) => typeof value === "string" || typeof value === "number")) return null
+    return entry
+  }
+  const note = noteFromRow(row)
+  if (!note) return null
+  entry.note = note
+  return entry
+}
+
+function noteFromRow(row: CatalogRow): CatalogEntry["note"] {
+  if (typeof row.dont_forget !== "number" || typeof row.archived !== "number") return null
+  const note = {
+    id: row.id,
+    type: row.type,
+    statement: row.statement,
+    body: row.body,
+    dontForget: row.dont_forget === 1,
+    archived: row.archived === 1,
+  }
+  if (!CatalogNoteValidator.Check(note)) return null
+  return note
+}
+
+export function corruptCatalog(): SearchIndexRefusal {
+  return { succeeded: false, reason: "corrupted", problems: ["the catalog does not match its schema"] }
+}

package/src/services/search-index/legacy.ts

@@ -0,0 +1,64 @@
+import { Value } from "typebox/value"
+
+import { type CatalogEntry, semanticFingerprint } from "#src/domain"
+import type { prepareCatalogStatements } from "./catalog-statements.ts"
+import { validCatalogEntry } from "./inventory.ts"
+import { invalidCatalog, writeCatalogEntry } from "./reconcile.ts"
+import { IndexEntrySchema } from "./schemas.ts"
+import type { prepareStatements } from "./statements.ts"
+import type { IndexEntry, IndexWriteResult } from "./types.ts"
+
+export function putLegacyEntry(
+  statements: ReturnType<typeof prepareStatements>,
+  catalog: ReturnType<typeof prepareCatalogStatements>,
+  entry: IndexEntry,
+): IndexWriteResult {
+  if (!Value.Check(IndexEntrySchema, entry) || !Number.isFinite(entry.modifiedMs)) {
+    return invalidCatalog("the entry does not match the index schema")
+  }
+  if (statements.byId.all(entry.id).length > 1) {
+    return invalidCatalog("duplicate ids require a path-keyed catalog mutation")
+  }
+  const converted = legacyEntry(entry)
+  if (!validCatalogEntry(converted)) return invalidCatalog("the entry does not have a valid catalog path")
+  statements.move.run(converted.path, entry.id)
+  writeCatalogEntry(catalog, converted)
+  statements.folder.run(entry.folder, converted.path)
+  catalog.prune.run()
+  catalog.advance.run("needs-population")
+  return { succeeded: true }
+}
+
+export function removeLegacyEntry(
+  statements: ReturnType<typeof prepareStatements>,
+  catalog: ReturnType<typeof prepareCatalogStatements>,
+  id: string,
+): IndexWriteResult {
+  if (statements.byId.all(id).length > 1) return invalidCatalog("duplicate ids require a path-keyed catalog mutation")
+  statements.remove.run({ id })
+  catalog.prune.run()
+  catalog.advance.run("needs-population")
+  return { succeeded: true }
+}
+
+function legacyEntry(entry: IndexEntry): CatalogEntry {
+  let path = `${entry.statement}.md`
+  if (entry.folder !== "") path = `${entry.folder}/${path}`
+  if (entry.archived && path.split("/")[0]?.toLowerCase() !== "archive") path = `archive/${path}`
+  return {
+    path,
+    stat: { size: entry.size, mtimeMs: entry.modifiedMs },
+    rawHash: entry.hash,
+    contentFingerprint: semanticFingerprint(entry),
+    validationFingerprint: "legacy-unvalidated",
+    needsFixing: false,
+    note: {
+      id: entry.id,
+      statement: entry.statement,
+      body: entry.body,
+      type: entry.type,
+      dontForget: entry.dontForget,
+      archived: entry.archived,
+    },
+  }
+}

package/src/services/search-index/location.ts

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto"
+import { join } from "node:path"
+
+import { comparablePath, type PathPlatform } from "#src/domain"
+import { INDEX_FILE_EXTENSION, INDEX_FILE_NAME_LENGTH } from "./constants.ts"
+
+export function indexFileFor(indexFolder: string, vaultPath: string, platform: PathPlatform): string {
+  const vaultKey = comparablePath(vaultPath, platform)
+  const name = createHash("sha256").update(vaultKey).digest("hex").slice(0, INDEX_FILE_NAME_LENGTH)
+
+  return join(indexFolder, `${name}${INDEX_FILE_EXTENSION}`)
+}

package/src/services/search-index/open.ts

@@ -0,0 +1,46 @@
+import { lstatSync, mkdirSync } from "node:fs"
+import { dirname } from "node:path"
+import { DatabaseSync } from "node:sqlite"
+
+import { closeFailedIndex } from "./cleanup.ts"
+import { indexFailure } from "./refusals.ts"
+import { initializeSchema } from "./schema.ts"
+import { SqliteSearchIndex } from "./storage.ts"
+import type { OpenIndexResult } from "./types.ts"
+
+export function openIndex(path: string): OpenIndexResult {
+  try {
+    for (const suffix of ["", "-journal", "-wal", "-shm"]) {
+      if (lstatSync(`${path}${suffix}`, { throwIfNoEntry: false })?.isSymbolicLink()) {
+        return {
+          succeeded: false,
+          reason: "unavailable",
+          problems: [`Index path must not be a link: ${path}${suffix}`],
+        }
+      }
+    }
+    mkdirSync(dirname(path), { recursive: true })
+    return initializeIndex(new DatabaseSync(path))
+  } catch (error) {
+    if (!(error instanceof Error)) {
+      throw error
+    }
+    return indexFailure(error)
+  }
+}
+
+function initializeIndex(database: DatabaseSync): OpenIndexResult {
+  try {
+    const schema = initializeSchema(database)
+    if (!schema.succeeded) {
+      return closeFailedIndex(database, schema)
+    }
+
+    return { succeeded: true, output: new SqliteSearchIndex(database), rebuilt: schema.output }
+  } catch (error) {
+    if (!(error instanceof Error)) {
+      throw error
+    }
+    return closeFailedIndex(database, indexFailure(error))
+  }
+}

package/src/services/search-index/query.ts

@@ -0,0 +1,39 @@
+import type { StatementSync } from "node:sqlite"
+
+import { eng, removeStopwords } from "stopword"
+import { Value } from "typebox/value"
+
+import { BODY_WEIGHT, STATEMENT_WEIGHT, WORD_PATTERN } from "./constants.ts"
+import { SearchHitSchema, SearchOptionsSchema } from "./schemas.ts"
+import type { SearchHit, SearchOptions, SearchResult } from "./types.ts"
+
+export function readSearchHits(statement: StatementSync, query: string, options: SearchOptions): SearchResult {
+  if (!Value.Check(SearchOptionsSchema, options)) {
+    return { succeeded: false, reason: "invalid", problems: ["search options require a boolean includeArchived"] }
+  }
+
+  const terms = searchTermsOf(query)
+  if (terms.length === 0) return { succeeded: true, output: [] }
+
+  const rows = statement.all({
+    match: terms.map((term) => `"${term}"`).join(" OR "),
+    includeArchived: Number(options.includeArchived),
+    statementWeight: STATEMENT_WEIGHT,
+    bodyWeight: BODY_WEIGHT,
+  })
+  const hits: SearchHit[] = []
+  for (const row of rows) {
+    if (!Value.Check(SearchHitSchema, row) || !Number.isFinite(row.score)) {
+      return { succeeded: false, reason: "corrupted", problems: ["a search result does not match the index schema"] }
+    }
+    hits.push(row)
+  }
+  return { succeeded: true, output: hits }
+}
+
+export function searchTermsOf(query: string): string[] {
+  const words = query.toLowerCase().match(WORD_PATTERN)
+  if (!words) return []
+
+  return removeStopwords([...new Set(words)], eng)
+}

package/src/services/search-index/ranking.ts

@@ -0,0 +1,12 @@
+export {
+  cosine,
+  type EmbeddingProvider,
+  type FusedPath,
+  fuseRankings,
+  MINIMUM_SIMILARITY,
+  type MinimumSimilarities,
+  planVectorRefresh,
+  type ScoredPath,
+  semanticRanking,
+  type VectorRefreshPlan,
+} from "#src/domain"

package/src/services/search-index/reconcile.ts

@@ -0,0 +1,93 @@
+import { Value } from "typebox/value"
+
+import type { CatalogChanges, CatalogEntry } from "#src/domain"
+import { catalogFolder } from "#src/domain"
+import type { prepareCatalogStatements } from "./catalog-statements.ts"
+import { corruptCatalog, validCatalogEntry } from "./inventory.ts"
+import { CatalogChangesSchema, CatalogStateSchema } from "./schemas.ts"
+import type { CatalogWriteRow, IndexWriteResult, SearchIndexRefusal } from "./types.ts"
+
+export function writeCatalog(
+  statements: ReturnType<typeof prepareCatalogStatements>,
+  changes: CatalogChanges,
+): IndexWriteResult {
+  if (!validChanges(changes)) return invalidCatalog("the catalog changes are invalid or overlap")
+  const state = statements.state.get()
+  if (!Value.Check(CatalogStateSchema, state)) return corruptCatalog()
+  if (state.revision !== changes.expectedRevision) return staleCatalog()
+
+  for (const path of changes.deletes) statements.remove.run(path)
+  for (const entry of changes.upserts) writeCatalogEntry(statements, entry)
+  for (const update of changes.statUpdates) {
+    const result = statements.stat.run(update.stat.size, update.stat.mtimeMs, update.path)
+    if (result.changes !== 1) return invalidCatalog("stat updates require an existing path")
+  }
+  statements.prune.run()
+  statements.advance.run(changes.population)
+  return { succeeded: true }
+}
+
+function validChanges(changes: CatalogChanges): boolean {
+  const shape = {
+    expectedRevision: changes.expectedRevision,
+    upserts: changes.upserts,
+    deletes: changes.deletes,
+    statUpdates: changes.statUpdates,
+    population: changes.population,
+  }
+  if (!Value.Check(CatalogChangesSchema, shape)) return false
+  const paths = [
+    ...changes.deletes,
+    ...changes.upserts.map((entry) => entry.path),
+    ...changes.statUpdates.map((update) => update.path),
+  ]
+  return (
+    new Set(paths).size === paths.length &&
+    changes.upserts.every(validCatalogEntry) &&
+    changes.statUpdates.every((update) => Number.isFinite(update.stat.mtimeMs))
+  )
+}
+
+export function writeCatalogEntry(statements: ReturnType<typeof prepareCatalogStatements>, entry: CatalogEntry): void {
+  const row = emptyNoteRow(entry)
+  if (entry.note) {
+    row.id = entry.note.id
+    row.type = entry.note.type
+    row.statement = entry.note.statement
+    row.body = entry.note.body
+    row.dont_forget = 0
+    row.archived = 0
+    if (entry.note.dontForget) row.dont_forget = 1
+    if (entry.note.archived) row.archived = 1
+  }
+  statements.put.run({ ...row })
+}
+
+function emptyNoteRow(entry: CatalogEntry): CatalogWriteRow {
+  const row: CatalogWriteRow = {
+    path: entry.path,
+    folder: catalogFolder(entry.path),
+    id: null,
+    type: null,
+    statement: null,
+    body: null,
+    dont_forget: null,
+    archived: null,
+    size: entry.stat.size,
+    modified_ms: entry.stat.mtimeMs,
+    hash: entry.rawHash,
+    content_fingerprint: entry.contentFingerprint,
+    validation_fingerprint: entry.validationFingerprint,
+    needs_fixing: 0,
+  }
+  if (entry.needsFixing) row.needs_fixing = 1
+  return row
+}
+
+export function invalidCatalog(problem: string): IndexWriteResult {
+  return { succeeded: false, reason: "invalid", problems: [problem] }
+}
+
+export function staleCatalog(): SearchIndexRefusal {
+  return { succeeded: false, reason: "conflict", problems: ["the catalog changed since its inventory was read"] }
+}

package/src/services/search-index/recovery.ts

@@ -0,0 +1,56 @@
+import { randomUUID } from "node:crypto"
+import { renameSync, rmSync } from "node:fs"
+
+import { openIndex } from "./open.ts"
+import { indexFailure } from "./refusals.ts"
+import type { IndexLocation, IndexReplacement, OpenedIndex, OpenIndexResult } from "./types.ts"
+
+export function recoverIndex(location: IndexLocation): OpenIndexResult {
+  const opened = inspectExistingIndex(location)
+  if (opened.succeeded || opened.reason !== "corrupted") return opened
+
+  const temporaryPath = `${location.path}.rebuild-${randomUUID()}`
+  const replacement = installReplacement({ path: location.path, temporaryPath })
+  if (replacement.succeeded) return replacement
+
+  try {
+    rmSync(temporaryPath, { force: true })
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    replacement.problems.push(`temporary index cleanup failed: ${error.message}`)
+  }
+  return replacement
+}
+
+function inspectExistingIndex(location: IndexLocation): OpenIndexResult {
+  const opened = openIndex(location.path)
+  if (!opened.succeeded) return opened
+  return validateOpenedIndex(opened)
+}
+
+function validateOpenedIndex(opened: OpenedIndex): OpenIndexResult {
+  const inventory = opened.output.inventory()
+  const vectors = opened.output.vectors()
+  if (inventory.succeeded && vectors.succeeded) return opened
+  const closed = opened.output.close()
+  if (!closed.succeeded) return closed
+  if (!inventory.succeeded) return inventory
+  if (!vectors.succeeded) return vectors
+  return opened
+}
+
+function installReplacement(request: IndexReplacement): OpenIndexResult {
+  try {
+    const temporary = openIndex(request.temporaryPath)
+    if (!temporary.succeeded) return temporary
+    const closed = temporary.output.close()
+    if (!closed.succeeded) return closed
+    renameSync(request.temporaryPath, request.path)
+    const opened = openIndex(request.path)
+    if (!opened.succeeded) return opened
+    return { ...opened, rebuilt: true }
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    return indexFailure(error)
+  }
+}

package/src/services/search-index/refusals.ts

@@ -0,0 +1,21 @@
+import { SQLITE_CORRUPT, SQLITE_ERROR, SQLITE_NOTADB, SQLITE_PRIMARY_CODE_MASK } from "./constants.ts"
+import type { SearchIndexRefusal } from "./types.ts"
+
+export function indexFailure(error: Error): SearchIndexRefusal {
+  if ("errcode" in error && typeof error.errcode === "number") {
+    const primaryCode = error.errcode & SQLITE_PRIMARY_CODE_MASK
+    if (primaryCode === SQLITE_ERROR || primaryCode === SQLITE_CORRUPT || primaryCode === SQLITE_NOTADB) {
+      return { succeeded: false, reason: "corrupted", problems: [error.message] }
+    }
+  }
+
+  return { succeeded: false, reason: "unavailable", problems: [error.message] }
+}
+
+export function closedIndex(): SearchIndexRefusal {
+  return {
+    succeeded: false,
+    reason: "closed",
+    problems: ["the search index is closed or unusable; open a new connection"],
+  }
+}