@dzhechkov/harness-core 0.8.29 → 0.8.31

package/src/sqlite-read-helpers.ts

@@ -0,0 +1,128 @@
+/**
+ * Small, shared helpers for the READ-ONLY sqlite paths (`book-kb.ts`, `agentdb-index.ts`,
+ * `patterns.ts`) — feature `readonly-residuals`.
+ *
+ * Two residuals fixed here (`features/readonly-residuals/01_requirements.md`):
+ *
+ * FR-1. `applyReadonlyPragmas` closes a handle that was already opened by
+ * `openSqliteReadOnly` (`@dzhechkov/memory`) if the follow-up `busy_timeout` pragma throws.
+ * Before this helper existed, `book-kb.ts`/`agentdb-index.ts` called `db.pragma(...)`
+ * directly on the handle's `db`, outside any `try` — a pragma failure left BOTH the native
+ * connection and a tmp-copy directory (ADR-001 ladder rung 2) leaked, because `handle.cleanup()`
+ * is only wired into the `close()` this code never reaches.
+ *
+ * FR-2. `classifySqliteReadFailure` tells apart "the native module isn't installed here"
+ * (silent JSON fallback, unchanged behaviour) from "the store file itself is unreadable"
+ * (corrupt file, permission failure, …) — the second case used to be swallowed by the same
+ * bare `catch {}` in `patterns.ts`, so a corrupted `patterns.sqlite` silently looked like
+ * "fewer lessons" instead of "the store broke". `warnOnce` prints that second case exactly
+ * once per process, on stderr, without changing the JSON-fallback data path.
+ */
+
+/** Minimal shape `applyReadonlyPragmas` needs from an `openSqliteReadOnly` handle. */
+export interface PragmaTarget {
+  readonly db: { pragma: (sql: string) => void; close: () => void };
+  readonly cleanup: () => void;
+}
+
+function closeQuietly(db: { close: () => void }): void {
+  try {
+    db.close();
+  } catch {
+    // already failing on the caller's side — a close failure here must not mask the real cause
+  }
+}
+
+/**
+ * Run `fn()` and swallow any exception it throws — used for `handle.cleanup()` in the
+ * pragma-failure path (fix round 1, MEDIUM #2): a throwing `cleanup()` must not replace the
+ * original pragma error the caller is already in the middle of rethrowing.
+ */
+function cleanupQuietly(fn: () => void): void {
+  try {
+    fn();
+  } catch {
+    // the pragma failure is the error of record — a cleanup failure here must not mask it
+  }
+}
+
+/**
+ * Run `db.pragma('busy_timeout = 5000')` on an already-opened read-only handle. If the pragma
+ * throws, the connection is closed and `handle.cleanup()` is called (removing a tmp-copy
+ * directory, ADR-001 rung 2) BEFORE rethrowing — so a pragma failure never leaks either the
+ * native connection or the temporary copy. Both `close()` and `cleanup()` are individually
+ * guarded (`closeQuietly` / `cleanupQuietly`, fix round 1, MEDIUM #2) so that EITHER one throwing
+ * still lets the original pragma cause reach the caller with the db path attached, and both are
+ * still attempted exactly once each regardless of which one (if any) throws.
+ */
+export function applyReadonlyPragmas(handle: PragmaTarget, path: string): void {
+  try {
+    handle.db.pragma('busy_timeout = 5000'); // harmless on a readonly connection — kept for parity with the writer opener
+  } catch (err) {
+    closeQuietly(handle.db);
+    cleanupQuietly(() => handle.cleanup());
+    const cause = err instanceof Error ? err.message : String(err);
+    throw new Error(`failed to prepare ${path} for reading: ${cause}`);
+  }
+}
+
+/** Which of the two known catch-all reasons a store-opener failure names. */
+export type SqliteReadFailureKind = 'native-unavailable' | 'store-unreadable';
+
+/**
+ * Loader-specific signatures of "the `better-sqlite3` native module itself could not be loaded"
+ * (fix round 1, MEDIUM #1 — narrows the classifier after Codex review found the previous bare
+ * `/better-sqlite3/.test(msg)` swallowed `better-sqlite3: file is not a database`, a genuine
+ * corruption, as if the module were merely absent). Each pattern names a load-time failure mode,
+ * never a runtime/data failure that merely happens to mention the package name.
+ */
+const NATIVE_LOADER_PATTERNS: readonly RegExp[] = [
+  /Cannot find module ['"]?better-sqlite3/,
+  /better-sqlite3 is unavailable/,
+  /Could not locate the bindings file/,
+  /was compiled against a different Node\.js version/,
+  /invalid ELF header/,
+  /NODE_MODULE_VERSION/,
+];
+
+/**
+ * Classify an error caught around `SqliteBackend.openReadOnly` (or an equivalent opener):
+ * `'native-unavailable'` only when the failure is genuinely about `better-sqlite3` failing to
+ * LOAD — either `code === 'MODULE_NOT_FOUND'` with `better-sqlite3` named in the message or
+ * `requireStack` (a bare `MODULE_NOT_FOUND` for an unrelated module is NOT this — it is a
+ * different bug and must not be hidden as "native unavailable"), or the message matches one of
+ * the {@link NATIVE_LOADER_PATTERNS} native-module-loader signatures (missing module, ABI/version
+ * mismatch, corrupt/foreign binary). The existing silent JSON fallback is correct here, nothing
+ * changes. Anything else — a corrupt file (`file is not a database`), a permission failure, a
+ * genuinely unreadable store — is `'store-unreadable'`: still falls back to JSON (FR-2 does not
+ * change returned data), but the caller is expected to warn once via {@link warnOnce}.
+ */
+export function classifySqliteReadFailure(err: unknown): SqliteReadFailureKind {
+  const code = (err as { code?: string } | undefined)?.code;
+  const msg = err instanceof Error ? err.message : String(err);
+  const requireStackRaw = (err as { requireStack?: unknown } | undefined)?.requireStack;
+  const requireStack = Array.isArray(requireStackRaw) ? requireStackRaw.join('\n') : '';
+
+  if (code === 'MODULE_NOT_FOUND' && (/better-sqlite3/.test(msg) || /better-sqlite3/.test(requireStack))) {
+    return 'native-unavailable';
+  }
+  if (NATIVE_LOADER_PATTERNS.some((re) => re.test(msg))) return 'native-unavailable';
+  return 'store-unreadable';
+}
+
+const warnedKeys = new Set<string>();
+
+/**
+ * Write `text` to stderr the first time this exact `key` is seen in this process, and never
+ * again. Used to surface a `'store-unreadable'` classification exactly once per store path per
+ * process, instead of once per read call.
+ */
+export function warnOnce(key: string, text: string): void {
+  if (warnedKeys.has(key)) return;
+  warnedKeys.add(key);
+  try {
+    process.stderr.write(`${text}\n`);
+  } catch {
+    // a closed/broken stderr must not break the caller's fallback
+  }
+}

package/src/statusline.ts

@@ -70,15 +70,30 @@ export interface StatuslineData {
   readonly patterns: number;
   /** Absent on parity; missing/unreadable mirror is explicitly unavailable. */
   readonly patternMirror?:
-    | { readonly state: 'different'; readonly lexical: number; readonly vector: number }
+    | {
+      readonly state: 'in-sync' | 'different';
+      readonly lexicalMirrorable: number;
+      readonly vector: number;
+      readonly excluded: { readonly class: number; readonly noise: number };
+    }
     | { readonly state: 'unavailable' };
+  /** Vector-mirror inventory; absence is explicit instead of being encoded as a missing field. */
+  readonly mirror: {
+    readonly available: boolean;
+    readonly rows: number;
+    readonly lessons: number;
+    readonly pending: number;
+    readonly source: 'agentdb';
+  };
   /** Exact lexical-tier availability split; omitted when the enhanced readonly count cannot be established. */
   readonly patternBreakdown?: {
-    readonly source: 'lexical';
+    readonly source: 'lexical' | 'lexical+mirror';
     readonly active: number;
     readonly quarantined: number;
     /** True once quarantine contains at least one third of the lexical pool. */
     readonly attention: boolean;
+    /** Exact label drift by dzId; present only when both tiers expose readable identities. */
+    readonly tierParity?: { readonly lexicalOnly: number; readonly mirrorOnly: number };
     /** Absolute lexical/vector quarantine-label delta, present only above the tolerated drift threshold. */
     readonly tierDelta?: number;
   };
@@ -103,6 +118,8 @@ export interface StatuslineData {
 /** Render-ready details for a non-healthy store verdict. */
 export interface StatuslineStoreHealth {
   readonly verdict: Exclude<StoreHealthVerdict, 'ok' | 'no-mark'>;
+  /** Explanation for a health verdict that cannot be inferred from counts alone. */
+  readonly reason?: string;
   /** Previous maximum for the affected store tier. */
   readonly previousMax?: number;
   /** Snapshot directory used by cold-start recovery guidance. */
@@ -643,6 +660,8 @@ export function statuslineData(projectRoot: string, now: number = Date.now()): S
             ? [basename(rows.vectorSourcePath)] : []),
         ],
       };
+    } else if (health.verdict === 'busy') {
+      storeHealth = { verdict: health.verdict, reason: health.reason };
     } else if (health.verdict === 'source-changed') {
       storeHealth = { verdict: health.verdict };
     }
@@ -659,14 +678,38 @@ export function statuslineData(projectRoot: string, now: number = Date.now()): S
   // зеркалом не пользуется, он горел бы всегда, а вечно горящий показатель не несёт сведений.
   // Зеркало ЕСТЬ, но прочитать или разложить его не удалось: это отказ инструмента, и он горит.
   const mirrorLessons = storeRows?.vectorLessonRows;
+  const mirrorRows = storeRows?.vectorRows;
   const mirrorAbsent = storeRows !== undefined && storeRows.vectorSourcePath === undefined;
+  const lexicalMirrorable = storeRows?.lexicalMirrorableRows;
+  const excluded = {
+    class: storeRows?.lexicalExcludedClassRows ?? 0,
+    noise: storeRows?.lexicalExcludedNoiseRows ?? 0,
+  };
+  const mirrorAvailable = storeRows?.vectorSourcePath !== undefined
+    && typeof mirrorRows === 'number'
+    && mirrorLessons !== undefined;
   const patternMirror: StatuslineData['patternMirror'] = mirrorAbsent
     ? undefined
-    : storeRows === undefined || storeRows.vectorRows === 'unreadable' || mirrorLessons === undefined
+    : storeRows === undefined || storeRows.vectorRows === 'unreadable' || storeRows.vectorRows === 'busy'
+      || mirrorLessons === undefined || lexicalMirrorable === undefined
       ? { state: 'unavailable' }
-      : mirrorLessons !== patterns
-        ? { state: 'different', lexical: patterns, vector: mirrorLessons }
-        : undefined;
+      : {
+        state: mirrorLessons !== lexicalMirrorable ? 'different' : 'in-sync',
+        lexicalMirrorable,
+        vector: mirrorLessons,
+        excluded,
+      };
+  const mirror: StatuslineData['mirror'] = {
+    available: mirrorAvailable,
+    rows: typeof mirrorRows === 'number' ? mirrorRows : 0,
+    lessons: mirrorAvailable ? mirrorLessons : 0,
+    pending: mirrorAbsent && lexicalMirrorable !== undefined
+      ? lexicalMirrorable
+      : mirrorAvailable && lexicalMirrorable !== undefined
+        ? Math.max(0, lexicalMirrorable - mirrorLessons)
+        : 0,
+    source: 'agentdb',
+  };
 
   let patternBreakdown: StatuslineData['patternBreakdown'];
   try {
@@ -674,14 +717,22 @@ export function statuslineData(projectRoot: string, now: number = Date.now()): S
       && typeof storeRows.lexicalRows === 'number'
       && typeof storeRows.lexicalQuarantinedRows === 'number') {
       const quarantined = storeRows.lexicalQuarantinedRows;
-      const tierDelta = typeof storeRows.vectorQuarantinedRows === 'number'
-        ? Math.abs(quarantined - storeRows.vectorQuarantinedRows)
+      const tierDelta = mirrorAvailable
+        && typeof storeRows.lexicalMirrorableQuarantinedRows === 'number'
+        && typeof storeRows.vectorQuarantinedRows === 'number'
+        ? Math.abs(storeRows.lexicalMirrorableQuarantinedRows - storeRows.vectorQuarantinedRows)
         : undefined;
       patternBreakdown = {
-        source: 'lexical',
+        source: mirrorAvailable ? 'lexical+mirror' : 'lexical',
         active: storeRows.lexicalRows - quarantined,
         quarantined,
         attention: quarantined > 0 && quarantined * 3 >= storeRows.lexicalRows,
+        ...(storeRows.quarantineTierParity === undefined ? {} : {
+          tierParity: {
+            lexicalOnly: storeRows.quarantineTierParity.lexicalOnly,
+            mirrorOnly: storeRows.quarantineTierParity.mirrorOnly,
+          },
+        }),
         ...(tierDelta !== undefined && tierDelta > QUARANTINE_TIER_DRIFT_TOLERANCE ? { tierDelta } : {}),
       };
     }
@@ -719,6 +770,7 @@ export function statuslineData(projectRoot: string, now: number = Date.now()): S
 
   return {
     patterns,
+    mirror,
     ...(patternMirror !== undefined ? { patternMirror } : {}),
     ...(patternBreakdown !== undefined ? { patternBreakdown } : {}),
     ...(usedPatterns !== undefined ? { usedPatterns } : {}),