@cleocode/core 2026.4.98 → 2026.4.99

package/src/sentient/ingesters/brain-ingester.ts

@@ -0,0 +1,122 @@
+/**
+ * BRAIN Ingester — Tier-2 proposal candidate source.
+ *
+ * Queries brain.db for recurring-pain observations (citation_count >= 3,
+ * last 7 days, quality_score >= 0.5) and returns ranked ProposalCandidate[].
+ *
+ * Design principles:
+ * - NO LLM calls. All data comes from structured SQL queries.
+ * - Title is template-generated: `[T2-BRAIN] Recurring issue: {title}`.
+ *   This is the prompt-injection defence from T1008 §3.6.
+ * - Failures are swallowed: returns empty array + logs warning.
+ *   Brain.db absence must never crash the propose tick.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+
+import type { DatabaseSync } from 'node:sqlite';
+import type { ProposalCandidate } from '@cleocode/contracts';
+
+// ---------------------------------------------------------------------------
+// Brain observation row (raw SQL result)
+// ---------------------------------------------------------------------------
+
+interface BrainObservationRow {
+  id: string;
+  title: string | null;
+  text: string;
+  citation_count: number;
+  quality_score: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Maximum candidates returned from a single brain ingester pass. */
+export const BRAIN_INGESTER_LIMIT = 10;
+
+/** Minimum citation count for a brain entry to be considered. */
+export const BRAIN_MIN_CITATION_COUNT = 3;
+
+/** Minimum quality score for a brain entry to be considered. */
+export const BRAIN_MIN_QUALITY_SCORE = 0.5;
+
+/** Lookback window in days for brain observations. */
+export const BRAIN_LOOKBACK_DAYS = 7;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute candidate weight from citation_count and quality_score.
+ * Formula: `(citation_count / 10) * quality_score` capped at 1.0.
+ */
+export function computeBrainWeight(citationCount: number, qualityScore: number): number {
+  return Math.min((citationCount / 10) * qualityScore, 1.0);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the BRAIN ingester against the provided DatabaseSync handle.
+ *
+ * Returns at most {@link BRAIN_INGESTER_LIMIT} candidates, sorted by weight
+ * descending. Returns an empty array if the database has no matching entries
+ * or if any error occurs (errors are swallowed to never crash the tick).
+ *
+ * @param nativeDb - Open DatabaseSync handle to brain.db. May be null if
+ *   brain.db has not been initialised; this is treated as zero candidates.
+ * @returns Ranked ProposalCandidate array (may be empty).
+ */
+export function runBrainIngester(nativeDb: DatabaseSync | null): ProposalCandidate[] {
+  if (!nativeDb) {
+    return [];
+  }
+
+  try {
+    const stmt = nativeDb.prepare(`
+      SELECT id, title, text, citation_count, quality_score
+      FROM brain_observations
+      WHERE type IN ('bugfix', 'decision')
+        AND citation_count >= :minCitations
+        AND created_at >= datetime('now', :lookback)
+        AND quality_score >= :minQuality
+      ORDER BY citation_count DESC, quality_score DESC
+      LIMIT :limit
+    `);
+
+    const rows = stmt.all({
+      minCitations: BRAIN_MIN_CITATION_COUNT,
+      lookback: `-${BRAIN_LOOKBACK_DAYS} days`,
+      minQuality: BRAIN_MIN_QUALITY_SCORE,
+      limit: BRAIN_INGESTER_LIMIT,
+    }) as unknown as BrainObservationRow[];
+
+    const candidates: ProposalCandidate[] = rows.map((row) => {
+      const label = row.title ?? row.text.slice(0, 80);
+      return {
+        source: 'brain' as const,
+        sourceId: row.id,
+        title: `[T2-BRAIN] Recurring issue: ${label}`,
+        rationale: `Brain entry ${row.id} cited ${row.citation_count} times (quality ${row.quality_score.toFixed(2)}) in the last ${BRAIN_LOOKBACK_DAYS} days`,
+        weight: computeBrainWeight(row.citation_count, row.quality_score),
+      };
+    });
+
+    // Sort descending by weight (DB ORDER BY handles primary sort, but
+    // weight formula may produce different ordering than raw column order).
+    candidates.sort((a, b) => b.weight - a.weight);
+
+    return candidates;
+  } catch (err) {
+    // Best-effort: log warning but never throw from an ingester.
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[sentient/brain-ingester] WARNING: ${message}\n`);
+    return [];
+  }
+}

package/src/sentient/ingesters/nexus-ingester.ts

@@ -0,0 +1,171 @@
+/**
+ * Nexus Ingester — Tier-2 proposal candidate source.
+ *
+ * Queries nexus.db for structural anomalies and returns ranked
+ * ProposalCandidate[]. Two query patterns:
+ *
+ *   A. Orphaned callees: functions that have many callers but make no calls
+ *      themselves (zero-import, high-in-degree). Suggests dead-end sinks
+ *      that may be candidates for abstraction or documentation.
+ *
+ *   B. Over-coupled nodes: symbols with total degree (in + out edges) > 20,
+ *      suggesting high coupling that should be refactored.
+ *
+ * Design principles:
+ * - NO LLM calls. All data comes from structured SQL queries.
+ * - Title is template-generated: `[T2-NEXUS] ...`. Prompt-injection defence.
+ * - Failures are swallowed: returns empty array + logs warning.
+ *   Nexus.db absence must never crash the propose tick.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+
+import type { DatabaseSync } from 'node:sqlite';
+import type { ProposalCandidate } from '@cleocode/contracts';
+
+// ---------------------------------------------------------------------------
+// Raw row types
+// ---------------------------------------------------------------------------
+
+interface OrphanCalleeRow {
+  id: string;
+  name: string;
+  file_path: string;
+  caller_count: number;
+}
+
+interface HighDegreeRow {
+  id: string;
+  name: string;
+  file_path: string;
+  degree: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Base weight for all nexus candidates (structural signals, lower priority than brain). */
+export const NEXUS_BASE_WEIGHT = 0.3;
+
+/** Minimum caller count for orphaned-callee detection. */
+export const NEXUS_MIN_CALLER_COUNT = 5;
+
+/** Minimum total degree for over-coupling detection. */
+export const NEXUS_MIN_DEGREE = 20;
+
+/** Maximum results per query. */
+export const NEXUS_QUERY_LIMIT = 5;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a deduplication key that is stable across query A and query B.
+ * Both queries reference the same nexus node table, so using the node id
+ * directly as sourceId is sufficient.
+ */
+function toFingerprint(nodeId: string): string {
+  return nodeId;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the Nexus ingester against the provided DatabaseSync handle.
+ *
+ * Returns candidates from both orphaned-callee (Query A) and high-degree
+ * (Query B) detection, merged without duplication. Returns an empty array
+ * if the database has no matching entries or if any error occurs.
+ *
+ * @param nativeDb - Open DatabaseSync handle to nexus.db. May be null if
+ *   nexus.db has not been initialised; this is treated as zero candidates.
+ * @returns Ranked ProposalCandidate array (may be empty).
+ */
+export function runNexusIngester(nativeDb: DatabaseSync | null): ProposalCandidate[] {
+  if (!nativeDb) {
+    return [];
+  }
+
+  const seenIds = new Set<string>();
+  const candidates: ProposalCandidate[] = [];
+
+  try {
+    // Query A: orphaned callees (many callers, zero outbound calls).
+    const stmtA = nativeDb.prepare(`
+      SELECT n.id, n.name, n.file_path, COUNT(r.id) as caller_count
+      FROM nexus_nodes n
+      JOIN nexus_relations r ON r.target_id = n.id AND r.kind = 'calls'
+      WHERE NOT EXISTS (
+        SELECT 1 FROM nexus_relations r2
+        WHERE r2.source_id = n.id AND r2.kind = 'calls'
+      )
+      AND n.kind = 'function'
+      GROUP BY n.id
+      HAVING caller_count > :minCallers
+      ORDER BY caller_count DESC
+      LIMIT :limit
+    `);
+
+    const rowsA = stmtA.all({
+      minCallers: NEXUS_MIN_CALLER_COUNT,
+      limit: NEXUS_QUERY_LIMIT,
+    }) as unknown as OrphanCalleeRow[];
+
+    for (const row of rowsA) {
+      const fp = toFingerprint(row.id);
+      if (seenIds.has(fp)) continue;
+      seenIds.add(fp);
+      candidates.push({
+        source: 'nexus' as const,
+        sourceId: row.id,
+        title: `[T2-NEXUS] Over-coupled symbol: ${row.name} (${row.caller_count} callers)`,
+        rationale: `Function ${row.name} in ${row.file_path} has ${row.caller_count} callers but makes no outbound calls — review for abstraction opportunity`,
+        weight: NEXUS_BASE_WEIGHT,
+      });
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[sentient/nexus-ingester] WARNING query A: ${message}\n`);
+  }
+
+  try {
+    // Query B: high-degree nodes (over-coupling).
+    const stmtB = nativeDb.prepare(`
+      SELECT n.id, n.name, n.file_path, COUNT(r.id) as degree
+      FROM nexus_nodes n
+      JOIN nexus_relations r ON r.source_id = n.id OR r.target_id = n.id
+      GROUP BY n.id
+      HAVING degree > :minDegree
+      ORDER BY degree DESC
+      LIMIT :limit
+    `);
+
+    const rowsB = stmtB.all({
+      minDegree: NEXUS_MIN_DEGREE,
+      limit: NEXUS_QUERY_LIMIT,
+    }) as unknown as HighDegreeRow[];
+
+    for (const row of rowsB) {
+      const fp = toFingerprint(row.id);
+      if (seenIds.has(fp)) continue;
+      seenIds.add(fp);
+      candidates.push({
+        source: 'nexus' as const,
+        sourceId: row.id,
+        title: `[T2-NEXUS] Over-coupled symbol: ${row.name} (${row.degree} edges)`,
+        rationale: `Symbol ${row.name} in ${row.file_path} has ${row.degree} total edges — review for over-coupling`,
+        weight: NEXUS_BASE_WEIGHT,
+      });
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[sentient/nexus-ingester] WARNING query B: ${message}\n`);
+  }
+
+  return candidates;
+}

package/src/sentient/ingesters/test-ingester.ts

@@ -0,0 +1,205 @@
+/**
+ * Test Ingester — Tier-2 proposal candidate source.
+ *
+ * Reads two data sources:
+ *
+ *   Source A — `.cleo/audit/gates.jsonl`: CLEO evidence gate failure records.
+ *     Each line is a JSONL record. Lines where `failCount > 0` produce a
+ *     proposal suggesting a flaky-test guard be added for the failing task.
+ *
+ *   Source B — `.cleo/coverage-summary.json`: vitest coverage JSON summary.
+ *     Written by `vitest --coverage --reporter json-summary`. Lines where
+ *     `lines.pct < 80` produce a proposal suggesting coverage improvement.
+ *     If the file is absent, Source B returns zero candidates (no error).
+ *
+ * Design principles:
+ * - NO LLM calls. All data comes from structured file reads.
+ * - Title is template-generated. Prompt-injection defence (T1008 §3.6).
+ * - Failures are swallowed: returns empty array + logs warning.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ProposalCandidate } from '@cleocode/contracts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single line from gates.jsonl. */
+interface GateRecord {
+  taskId?: string;
+  gate?: string;
+  failCount?: number;
+  [key: string]: unknown;
+}
+
+/** Coverage summary entry for a single file. */
+interface CoverageEntry {
+  lines?: { pct?: number };
+  statements?: { pct?: number };
+  functions?: { pct?: number };
+  branches?: { pct?: number };
+}
+
+/** Shape of the JSON coverage summary file. */
+type CoverageSummary = Record<string, CoverageEntry>;
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Relative path from project root to gates.jsonl. */
+export const GATES_JSONL_PATH = '.cleo/audit/gates.jsonl' as const;
+
+/** Relative path from project root to the coverage summary. */
+export const COVERAGE_SUMMARY_PATH = '.cleo/coverage-summary.json' as const;
+
+/** Coverage line percentage below which a proposal is emitted. */
+export const MIN_LINE_COVERAGE_PCT = 80;
+
+/** Base weight for all test ingester candidates. */
+export const TEST_BASE_WEIGHT = 0.5;
+
+// ---------------------------------------------------------------------------
+// Source A: gates.jsonl
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse gates.jsonl and return one candidate per task that has any gate
+ * with `failCount > 0`.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns Proposal candidates (may be empty).
+ */
+function runGatesIngester(projectRoot: string): ProposalCandidate[] {
+  const gatesPath = join(projectRoot, GATES_JSONL_PATH);
+
+  let raw: string;
+  try {
+    raw = readFileSync(gatesPath, 'utf-8');
+  } catch {
+    // File absent or unreadable — not an error.
+    return [];
+  }
+
+  const candidates: ProposalCandidate[] = [];
+  const seenKeys = new Set<string>();
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    let record: GateRecord;
+    try {
+      record = JSON.parse(trimmed) as GateRecord;
+    } catch {
+      // Skip malformed lines.
+      continue;
+    }
+
+    const taskId = record.taskId;
+    const gate = record.gate ?? 'unknown';
+    const failCount = record.failCount ?? 0;
+
+    if (typeof taskId !== 'string' || failCount <= 0) continue;
+
+    const key = `${taskId}.${gate}`;
+    if (seenKeys.has(key)) continue;
+    seenKeys.add(key);
+
+    candidates.push({
+      source: 'test' as const,
+      sourceId: key,
+      title: `[T2-TEST] Fix flaky gate: ${taskId}.${gate}`,
+      rationale: `Gate '${gate}' on task ${taskId} has failed ${failCount} time(s)`,
+      weight: TEST_BASE_WEIGHT,
+    });
+  }
+
+  return candidates;
+}
+
+// ---------------------------------------------------------------------------
+// Source B: coverage-summary.json
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the vitest coverage summary and return one candidate per file with
+ * line coverage below {@link MIN_LINE_COVERAGE_PCT}.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns Proposal candidates (may be empty; empty if file absent).
+ */
+function runCoverageIngester(projectRoot: string): ProposalCandidate[] {
+  const coveragePath = join(projectRoot, COVERAGE_SUMMARY_PATH);
+
+  let summary: CoverageSummary;
+  try {
+    const raw = readFileSync(coveragePath, 'utf-8');
+    summary = JSON.parse(raw) as CoverageSummary;
+  } catch {
+    // File absent or malformed — not an error, return zero candidates.
+    return [];
+  }
+
+  const candidates: ProposalCandidate[] = [];
+
+  for (const [filePath, entry] of Object.entries(summary)) {
+    // Skip the 'total' synthetic key if present.
+    if (filePath === 'total') continue;
+
+    const pct = entry?.lines?.pct;
+    if (typeof pct !== 'number' || pct >= MIN_LINE_COVERAGE_PCT) continue;
+
+    candidates.push({
+      source: 'test' as const,
+      sourceId: filePath,
+      title: `[T2-TEST] Increase coverage: ${filePath} (${pct}% lines)`,
+      rationale: `File ${filePath} has ${pct}% line coverage (target: ${MIN_LINE_COVERAGE_PCT}%)`,
+      weight: TEST_BASE_WEIGHT,
+    });
+  }
+
+  return candidates;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the test ingester against both data sources.
+ *
+ * Merges Source A (gates.jsonl) and Source B (coverage-summary.json) without
+ * duplication. Returns an empty array if both sources yield nothing or if
+ * errors occur (errors are swallowed).
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns Combined ProposalCandidate array (may be empty).
+ */
+export function runTestIngester(projectRoot: string): ProposalCandidate[] {
+  try {
+    const gatesCandidates = runGatesIngester(projectRoot);
+    const coverageCandidates = runCoverageIngester(projectRoot);
+
+    // Merge, deduplicate by sourceId.
+    const seenSourceIds = new Set<string>();
+    const merged: ProposalCandidate[] = [];
+
+    for (const candidate of [...gatesCandidates, ...coverageCandidates]) {
+      if (seenSourceIds.has(candidate.sourceId)) continue;
+      seenSourceIds.add(candidate.sourceId);
+      merged.push(candidate);
+    }
+
+    return merged;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[sentient/test-ingester] WARNING: ${message}\n`);
+    return [];
+  }
+}

package/src/sentient/proposal-rate-limiter.ts

@@ -0,0 +1,172 @@
+/**
+ * Proposal Rate Limiter — Transactional DB-enforced daily cap.
+ *
+ * Enforces a maximum of N proposals per day per source tag, using a
+ * BEGIN IMMEDIATE transaction with COUNT + conditional INSERT pattern.
+ *
+ * Design rationale (T1008 §3.2):
+ * - In-process counters do not survive daemon restart, and two daemon
+ *   instances could both allow N/day if enforcement is not in the DB.
+ * - The `sentient.lock` advisory lock (daemon.ts) prevents two daemons
+ *   from running concurrently, but the transactional count check provides
+ *   belt-and-suspenders protection against TOCTOU races.
+ * - SQLite partial unique indexes cannot enforce count > 1, so the
+ *   BEGIN IMMEDIATE + COUNT + INSERT pattern is used instead.
+ *
+ * The "day" boundary is determined by SQLite's `date('now')` (UTC).
+ * Proposals counted include ALL non-terminal statuses (proposed, pending,
+ * active, done) — an accepted proposal still consumes a daily slot.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * The meta proposedBy tag written to `tasks.metadata_json` by the Tier-2
+ * proposer. This tag is the query key for rate-limit counting.
+ */
+export const SENTIENT_TIER2_TAG = 'sentient-tier2' as const;
+
+/**
+ * Default maximum number of Tier-2 proposals per UTC day.
+ * Can be overridden by callers.
+ */
+export const DEFAULT_DAILY_PROPOSAL_LIMIT = 3;
+
+/**
+ * SQL error code string returned when BEGIN IMMEDIATE fails because another
+ * write transaction is in progress.
+ */
+const SQLITE_BUSY_CODE = 'SQLITE_BUSY';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Count the number of Tier-2 proposals created today (UTC).
+ *
+ * Counts tasks where:
+ *   - `labels_json` contains `'sentient-tier2'` (the Tier-2 marker label)
+ *   - `date(created_at) = date('now')`
+ *   - `status IN ('proposed', 'pending', 'active', 'done')` — terminal
+ *     states that were proposed today still count toward the daily cap so
+ *     that accepted proposals don't free a slot for another proposal.
+ *
+ * The `LIKE` pattern is intentional: labels_json is a JSON array stored as
+ * text, and `'sentient-tier2'` is always a complete JSON string value within
+ * that array, making substring matching safe here.
+ *
+ * @param nativeDb - Open DatabaseSync handle to tasks.db.
+ * @returns Number of proposals created today. Returns 0 if DB is null.
+ */
+export function countTodayProposals(nativeDb: DatabaseSync | null): number {
+  if (!nativeDb) return 0;
+
+  const stmt = nativeDb.prepare(`
+    SELECT COUNT(*) as cnt
+    FROM tasks
+    WHERE labels_json LIKE :labelPattern
+      AND date(created_at) = date('now')
+      AND status IN ('proposed', 'pending', 'active', 'done')
+  `);
+
+  const row = stmt.get({ labelPattern: `%${SENTIENT_TIER2_TAG}%` }) as { cnt: number } | undefined;
+  return row?.cnt ?? 0;
+}
+
+/**
+ * Check whether the daily rate limit has been reached.
+ *
+ * @param nativeDb - Open DatabaseSync handle to tasks.db.
+ * @param limit - Daily cap (defaults to {@link DEFAULT_DAILY_PROPOSAL_LIMIT}).
+ * @returns `true` if the limit is reached or exceeded; `false` if capacity remains.
+ */
+export function isRateLimitExceeded(
+  nativeDb: DatabaseSync | null,
+  limit = DEFAULT_DAILY_PROPOSAL_LIMIT,
+): boolean {
+  return countTodayProposals(nativeDb) >= limit;
+}
+
+// ---------------------------------------------------------------------------
+// Transactional INSERT guard
+// ---------------------------------------------------------------------------
+
+/** Result of a transactional insert attempt. */
+export interface TransactionalInsertResult {
+  /** Whether the INSERT was committed. */
+  inserted: boolean;
+  /**
+   * The count read at the start of the transaction. Used for diagnostics
+   * and tests — lets callers verify the guard saw the expected count.
+   */
+  countBeforeInsert: number;
+  /**
+   * If `inserted = false` and this is set, the limit was the reason.
+   */
+  reason?: 'rate-limit' | 'busy';
+}
+
+/**
+ * Attempt to insert a pre-built task row inside a BEGIN IMMEDIATE transaction
+ * with a count check.
+ *
+ * Steps:
+ *   1. BEGIN IMMEDIATE (exclusive write lock on tasks.db)
+ *   2. COUNT proposals created today
+ *   3. If count >= limit: ROLLBACK, return `{ inserted: false, reason: 'rate-limit' }`
+ *   4. Otherwise: INSERT the row, COMMIT, return `{ inserted: true }`
+ *
+ * On SQLITE_BUSY: ROLLBACK + return `{ inserted: false, reason: 'busy' }`.
+ *
+ * @param nativeDb - Open DatabaseSync handle to tasks.db.
+ * @param insertSql - Parameterized INSERT SQL string.
+ * @param insertParams - Named parameters for the INSERT statement.
+ * @param limit - Daily cap.
+ * @returns Insert result.
+ */
+export function transactionalInsertProposal(
+  nativeDb: DatabaseSync,
+  insertSql: string,
+  insertParams: Record<string, SQLInputValue>,
+  limit = DEFAULT_DAILY_PROPOSAL_LIMIT,
+): TransactionalInsertResult {
+  try {
+    nativeDb.exec('BEGIN IMMEDIATE');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes(SQLITE_BUSY_CODE)) {
+      return { inserted: false, countBeforeInsert: 0, reason: 'busy' };
+    }
+    throw err;
+  }
+
+  try {
+    const countBeforeInsert = countTodayProposals(nativeDb);
+
+    if (countBeforeInsert >= limit) {
+      nativeDb.exec('ROLLBACK');
+      return { inserted: false, countBeforeInsert, reason: 'rate-limit' };
+    }
+
+    const stmt = nativeDb.prepare(insertSql);
+    stmt.run(insertParams);
+
+    nativeDb.exec('COMMIT');
+    return { inserted: true, countBeforeInsert };
+  } catch (err) {
+    try {
+      nativeDb.exec('ROLLBACK');
+    } catch {
+      // ignore rollback failure
+    }
+    throw err;
+  }
+}