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>
2026-07-11 00:42:43 +08:00
parent 44029676d4
commit e3e61cc7ab
25 changed files with 2173 additions and 471 deletions
@@ -0,0 +1,133 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { acquireWriterLease, writerLockPathFor } from '../scripts/writer-lease.ts';
+
+const require = createRequire(import.meta.url);
+const { DatabaseSync } = require('node:sqlite');
+const repoRoot = resolve(new URL('..', import.meta.url).pathname);
+
+test('a passive query does not mutate the index while a fresh daemon owns writes', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-daemon-arbitration-'));
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+
+  const db = new DatabaseSync(dbPath);
+  db.exec('CREATE TABLE index_state (jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER)');
+  const marker = db.prepare('INSERT INTO index_state (jsonl_path, mtime, lines_processed) VALUES (?, ?, 0)');
+  const now = Date.now();
+  marker.run('__app_heartbeat__', now);
+  db.close();
+
+  const queryPath = join(home, 'query.mjs');
+  writeFileSync(queryPath, "return 'read-only';");
+  const result = spawnSync(process.execPath, ['scripts/runtime.mjs', '--query', queryPath], {
+    cwd: repoRoot,
+    env: { ...process.env, HOME: home },
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.equal(JSON.parse(result.stdout), 'read-only');
+
+  const check = new DatabaseSync(dbPath, { readOnly: true });
+  const tables = check.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all().map(row => row.name);
+  check.close();
+  assert.deepEqual(tables, ['index_state']);
+});
+
+test('attune refuses to mutate the index while a fresh daemon owns writes', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-daemon-attune-'));
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec('CREATE TABLE index_state (jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER)');
+  const marker = db.prepare('INSERT INTO index_state (jsonl_path, mtime, lines_processed) VALUES (?, ?, 0)');
+  const now = Date.now();
+  marker.run('__app_heartbeat__', now);
+  db.close();
+
+  const attunePath = join(home, 'attune.mjs');
+  writeFileSync(attunePath, 'return true;');
+  const result = spawnSync(process.execPath, ['scripts/runtime.mjs', '--attune', attunePath], {
+    cwd: repoRoot,
+    env: { ...process.env, HOME: home },
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 1);
+  assert.match(JSON.parse(result.stdout).error, /daemon owns index writes/i);
+
+  const check = new DatabaseSync(dbPath, { readOnly: true });
+  const tables = check.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all().map(row => row.name);
+  check.close();
+  assert.deepEqual(tables, ['index_state']);
+});
+
+test('a passive query stays read-only when another process holds the writer lease', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-writer-owned-'));
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec('CREATE TABLE index_state (jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER)');
+  db.close();
+
+  const lease = acquireWriterLease({
+    lockPath: writerLockPathFor(dbPath),
+    openDb: path => new DatabaseSync(path),
+  });
+  assert.ok(lease);
+  try {
+    const queryPath = join(home, 'query.mjs');
+    writeFileSync(queryPath, "return 'writer-busy';");
+    const result = spawnSync(process.execPath, ['scripts/runtime.mjs', '--query', queryPath], {
+      cwd: repoRoot,
+      env: { ...process.env, HOME: home },
+      encoding: 'utf8',
+    });
+    assert.equal(result.status, 0, result.stderr || result.stdout);
+    assert.equal(JSON.parse(result.stdout), 'writer-busy');
+  } finally {
+    lease.release();
+  }
+
+  const check = new DatabaseSync(dbPath, { readOnly: true });
+  const tables = check.prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").all().map(row => row.name);
+  check.close();
+  assert.deepEqual(tables, ['index_state']);
+});
+
+test('a passive query fails closed when daemon ownership cannot be read', () => {
+  const home = mkdtempSync(join(tmpdir(), 'obelisk-daemon-ownership-error-'));
+  const obeliskDir = join(home, '.obelisk');
+  const dbPath = join(obeliskDir, 'obelisk.sqlite');
+  mkdirSync(obeliskDir, { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec('CREATE TABLE index_state (jsonl_path TEXT PRIMARY KEY)');
+  db.close();
+
+  const lease = acquireWriterLease({
+    lockPath: writerLockPathFor(dbPath),
+    openDb: path => new DatabaseSync(path),
+  });
+  assert.ok(lease);
+  try {
+    const queryPath = join(home, 'query.mjs');
+    writeFileSync(queryPath, "return 'ownership-unknown';");
+    const result = spawnSync(process.execPath, ['scripts/runtime.mjs', '--query', queryPath], {
+      cwd: repoRoot,
+      env: { ...process.env, HOME: home },
+      encoding: 'utf8',
+    });
+    assert.equal(result.status, 1, result.stderr || result.stdout);
+    assert.match(JSON.parse(result.stdout).error, /no such column: mtime/i);
+  } finally {
+    lease.release();
+  }
+});