fix: coordinate sqlite index writers
Implement the full ADR-0006 plan: three-layer separation of transaction
correctness, retry policy, and cross-process writer coordination.
Layer 1 — scripts/tx.ts (transaction correctness):
- runWriteTransaction executes work exactly once; no internal retry.
- BEGIN IMMEDIATE takes the write lock up front (avoids SQLITE_BUSY_SNAPSHOT).
- Guarded rollback: checks inTransaction() via adapter before attempting
ROLLBACK; never masks the primary exception.
- WriteTxDiagnostics attached to errors: phase, code, label,
rollbackSucceeded, rollbackError, transactionActive.
- Binding adapters (betterSqliteTransactionAdapter, nodeSqliteTransactionAdapter)
mapping better-sqlite3's `.inTransaction` and node:sqlite's `.isTransaction`.
- configureConnection centralizes WAL + synchronous + busy_timeout.
Layer 2 — scripts/write-coordinator.ts (retry policy):
- runRetryableWriteTransaction: bounded retry with total time budget.
- Only retries when the transaction confirmed ended (transactionActive=false)
and the error is SQLITE_BUSY during work/commit phase.
- BEGIN-phase BUSY = abort entire build (isBeginBusyFailure); the caller
returns `{ deferred: true, reason: 'writer_busy' }` instead of waiting.
- hasUnusableTransaction detects a still-active transaction after failure;
aborts the build immediately, never retries.
Layer 3 — scripts/writer-lease.ts (cross-process coordination):
- acquireWriterLease: dedicated writer.lock.sqlite with busy_timeout=0 +
BEGIN IMMEDIATE. Non-blocking attempt; bounded wait with retryDelayMs.
- writerLockPathFor derives lock path from the target DB path.
- Lease held for the entire build; released on completion or failure.
- Lock DB uses DELETE journal (not WAL); crash/close auto-releases.
- All consumers obey: skill acquires at build start (returns deferred if
unavailable); app daemon (via worker) acquires for its build cycle.
Build semantics changes:
- affectedSessionIds updated only after successful commit.
- BuildIndexResult gains skipped/skippedFiles for observability.
- Skill finalize failure now fails the build (was silently warned).
- Checkpoint changed to PASSIVE (TRUNCATE reserved for maintenance/exit).
- Skill buildIndex returns { deferred, reason } on lease contention;
indexer-service reschedules the build (deferredRetryMs) without publishing
a heartbeat (so the build-deferred state is visible to cross-process
arbitration).
- Service publishes heartbeat immediately on start() for correct arbitration.
Tests:
- tests/write-transaction.test.mjs: single-shot execution, diagnostics
propagation, auto-rolled-back transaction detected, rollback failure
captured as metadata, BEGIN IMMEDIATE semantics.
- tests/writer-lease.test.mjs: acquire/release, contention returns null,
bounded wait with release during budget.
- tests/app-writer-lease.test.mjs: better-sqlite3 adapter integration.
- tests/app-rollback-guard.test.mjs: rewritten — transient BUSY recovered
by coordinator, persistent BUSY skips file, begin-busy aborts build,
live-transaction aborts build, phantom affectedSessionIds prevented.
- tests/daemon-arbitration.test.mjs: skill defers to fresh app heartbeat,
builds when heartbeat is stale.
- tests/app-indexer-service.test.mjs: new cases for deferred-retry
scheduling and immediate heartbeat on start.
- app/tests/electron-concurrency.mjs + child: dual-child IPC structure for
real better-sqlite3 contention (holder acquires lock → build child starts
→ delayed release → result collected; persistent contention bounded).
ADR-0006 updated to reflect the implemented design.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
tommy0103
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
44029676d4
commit
e3e61cc7ab
+102
-22
@@ -9,6 +9,7 @@ import { writeHeartbeat } from './indexer.ts';
|
||||
import { createIndexerService } from './indexer-service.ts';
|
||||
import { createWorkerBuildIndex } from './indexer-worker-client.ts';
|
||||
import { buildRecapExportQuery } from './recap-capture-query.ts';
|
||||
import { acquireWriterLease, writerLockPathFor } from '../../../scripts/writer-lease.ts';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
@@ -41,6 +42,16 @@ let db;
|
||||
let indexerService;
|
||||
let indexerWorker;
|
||||
|
||||
type WriterLeaseMode = 'acquire' | 'caller-held';
|
||||
|
||||
function acquireAppWriterLease(dbPath: string, waitMs = 0) {
|
||||
return acquireWriterLease({
|
||||
lockPath: writerLockPathFor(dbPath),
|
||||
openDb: lockPath => new Database(lockPath),
|
||||
waitMs,
|
||||
});
|
||||
}
|
||||
|
||||
function getConfiguredClaudeDir() {
|
||||
const persisted = loadPersistedSettings();
|
||||
return persisted.claudeDir || DEFAULT_CLAUDE_DIR;
|
||||
@@ -60,15 +71,25 @@ function getPathsForClaudeDir(claudeDir = getConfiguredClaudeDir(), codexDir = g
|
||||
};
|
||||
}
|
||||
|
||||
function migrateLegacyDbIfNeeded(paths = getPathsForClaudeDir()) {
|
||||
function migrateLegacyDbIfNeeded(
|
||||
paths = getPathsForClaudeDir(),
|
||||
{ writerLeaseMode = 'acquire' }: { writerLeaseMode?: WriterLeaseMode } = {},
|
||||
) {
|
||||
if (fs.existsSync(paths.dbPath)) return;
|
||||
const legacyDbPath = path.join(paths.claudeDir, 'obelisk.sqlite');
|
||||
if (!fs.existsSync(legacyDbPath)) return;
|
||||
const lease = writerLeaseMode === 'acquire' ? acquireAppWriterLease(paths.dbPath) : null;
|
||||
if (writerLeaseMode === 'acquire' && !lease) return false;
|
||||
try {
|
||||
if (fs.existsSync(paths.dbPath)) return true;
|
||||
fs.mkdirSync(path.dirname(paths.dbPath), { recursive: true });
|
||||
fs.copyFileSync(legacyDbPath, paths.dbPath);
|
||||
return true;
|
||||
} catch (error) {
|
||||
console.warn?.(`Obelisk legacy DB migration skipped: ${(error as Error).message}`);
|
||||
return false;
|
||||
} finally {
|
||||
lease?.release();
|
||||
}
|
||||
}
|
||||
|
||||
@@ -151,15 +172,40 @@ function closeDb() {
|
||||
db = null;
|
||||
}
|
||||
|
||||
function openDb(dbPath = getPathsForClaudeDir().dbPath) {
|
||||
function openDb(
|
||||
dbPath = getPathsForClaudeDir().dbPath,
|
||||
{ writerLeaseMode = 'acquire' }: { writerLeaseMode?: WriterLeaseMode } = {},
|
||||
) {
|
||||
closeDb();
|
||||
if (!fs.existsSync(dbPath)) return null;
|
||||
db = new Database(dbPath, { readonly: false });
|
||||
db.pragma('journal_mode = WAL');
|
||||
migrateDb(db);
|
||||
db.pragma('busy_timeout = 5000');
|
||||
const lease = writerLeaseMode === 'acquire' ? acquireAppWriterLease(dbPath) : null;
|
||||
if (writerLeaseMode === 'caller-held' || lease) {
|
||||
try {
|
||||
db.pragma('journal_mode = WAL');
|
||||
migrateDb(db);
|
||||
} finally {
|
||||
lease?.release();
|
||||
}
|
||||
}
|
||||
return db;
|
||||
}
|
||||
|
||||
function runAppDbWrite(work: () => void): boolean {
|
||||
if (!db) return false;
|
||||
const lease = acquireAppWriterLease(getPathsForClaudeDir().dbPath, 250);
|
||||
if (!lease) {
|
||||
throw new Error('Obelisk index writer is busy; memory change was not applied');
|
||||
}
|
||||
try {
|
||||
work();
|
||||
return true;
|
||||
} finally {
|
||||
lease.release();
|
||||
}
|
||||
}
|
||||
|
||||
function notifyIndexUpdated(result: { affectedSessionIds?: unknown } = {}) {
|
||||
const affectedSessionIds = Array.isArray(result.affectedSessionIds)
|
||||
? [...new Set(result.affectedSessionIds.filter(Boolean))]
|
||||
@@ -200,8 +246,14 @@ function startIndexerService({ buildOnStart = false } = {}) {
|
||||
projectsDir: paths.projectsDir,
|
||||
dbPath: paths.dbPath,
|
||||
});
|
||||
openDb(paths.dbPath);
|
||||
notifyIndexUpdated(result);
|
||||
if (result?.deferred) {
|
||||
if (Array.isArray(result.affectedSessionIds) && result.affectedSessionIds.length) {
|
||||
notifyIndexUpdated(result);
|
||||
}
|
||||
} else {
|
||||
openDb(paths.dbPath);
|
||||
notifyIndexUpdated(result);
|
||||
}
|
||||
return result;
|
||||
},
|
||||
writeHeartbeat: () => writeHeartbeat({ dbPath: paths.dbPath }),
|
||||
@@ -520,16 +572,16 @@ ipcMain.handle('db:readMemoryFile', (_, filePath) => {
|
||||
});
|
||||
|
||||
ipcMain.handle('db:archiveMemory', (_, id, reason) => {
|
||||
if (!db) return false;
|
||||
db.prepare(`UPDATE memories SET deleted_at = ?, deleted_reason = ? WHERE id = ?`)
|
||||
.run(new Date().toISOString(), reason || 'Archived via panel', id);
|
||||
return true;
|
||||
return runAppDbWrite(() => {
|
||||
db.prepare(`UPDATE memories SET deleted_at = ?, deleted_reason = ? WHERE id = ?`)
|
||||
.run(new Date().toISOString(), reason || 'Archived via panel', id);
|
||||
});
|
||||
});
|
||||
|
||||
ipcMain.handle('db:restoreMemory', (_, id) => {
|
||||
if (!db) return false;
|
||||
db.prepare(`UPDATE memories SET deleted_at = NULL, deleted_reason = NULL WHERE id = ?`).run(id);
|
||||
return true;
|
||||
return runAppDbWrite(() => {
|
||||
db.prepare(`UPDATE memories SET deleted_at = NULL, deleted_reason = NULL WHERE id = ?`).run(id);
|
||||
});
|
||||
});
|
||||
|
||||
ipcMain.handle('db:getProjects', (_, opts = {}) => {
|
||||
@@ -830,8 +882,27 @@ ipcMain.handle('settings:rebuildIndex', async () => {
|
||||
indexerWorker = createWorkerBuildIndex();
|
||||
}
|
||||
cleanupDbFiles(tempDbPath);
|
||||
let writerLease: ReturnType<typeof acquireWriterLease> = null;
|
||||
try {
|
||||
migrateLegacyDbIfNeeded(paths);
|
||||
const writerLeasePath = writerLockPathFor(paths.dbPath);
|
||||
writerLease = acquireWriterLease({
|
||||
lockPath: writerLeasePath,
|
||||
openDb: lockPath => new Database(lockPath),
|
||||
waitMs: 2000,
|
||||
});
|
||||
if (!writerLease) {
|
||||
return {
|
||||
files: 0,
|
||||
latestSourceMtime: 0,
|
||||
affectedSessionIds: [],
|
||||
ftsRebuilt: false,
|
||||
skipped: 0,
|
||||
skippedFiles: [],
|
||||
deferred: true,
|
||||
reason: 'writer_busy',
|
||||
};
|
||||
}
|
||||
migrateLegacyDbIfNeeded(paths, { writerLeaseMode: 'caller-held' });
|
||||
const result = await indexerWorker.buildIndex({
|
||||
reason: 'manual-rebuild',
|
||||
force: true,
|
||||
@@ -840,21 +911,30 @@ ipcMain.handle('settings:rebuildIndex', async () => {
|
||||
projectsDir: paths.projectsDir,
|
||||
dbPath: tempDbPath,
|
||||
preserveDbPath: fs.existsSync(paths.dbPath) ? paths.dbPath : null,
|
||||
writerLeasePath,
|
||||
writerLeaseMode: 'caller-held',
|
||||
});
|
||||
if (result?.deferred) return result;
|
||||
closeDb();
|
||||
replaceDbWithTemp(tempDbPath, paths.dbPath);
|
||||
openDb(paths.dbPath);
|
||||
openDb(paths.dbPath, { writerLeaseMode: 'caller-held' });
|
||||
notifyIndexUpdated(result);
|
||||
return result;
|
||||
} finally {
|
||||
cleanupDbFiles(tempDbPath);
|
||||
if (!db) {
|
||||
try {
|
||||
openDb(paths.dbPath);
|
||||
} catch (error) {
|
||||
console.warn?.(`Obelisk DB reopen after rebuild failed: ${(error as Error).message}`);
|
||||
try {
|
||||
cleanupDbFiles(tempDbPath);
|
||||
if (!db) {
|
||||
try {
|
||||
openDb(paths.dbPath, {
|
||||
writerLeaseMode: writerLease ? 'caller-held' : 'acquire',
|
||||
});
|
||||
} catch (error) {
|
||||
console.warn?.(`Obelisk DB reopen after rebuild failed: ${(error as Error).message}`);
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
writerLease?.release();
|
||||
if (shouldRestartWatcher) startIndexerService({ buildOnStart: false });
|
||||
}
|
||||
if (shouldRestartWatcher) startIndexerService({ buildOnStart: false });
|
||||
}
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user