rust: retention/cap enforcement for the SQLite audit backend

Closes the last documented gap from the SQLite cutover slice. Two new
Rust functions, trim_audit_events_to_cap and purge_audit_events_older_than
- both single indexed DELETEs, cheap regardless of table size (unlike the
JSON backend's full-file-rewrite equivalent, which is why that backend
needed a soft cap with batching in the first place). audit-log-store.ts's
SQLite write path now enforces the same MAX_EVENTS/TRIM_BATCH cap and
age-based retention as the JSON backend, with equivalent semantics
(purge runs on every write when retention is configured; trim still
batches to avoid a DELETE per insert, though a single trim isn't
expensive here either).

Found and fixed a real bug in the process: get_last_audit_event_hash
crashed on a legacy-shaped last event (NULL event_hash column) - none of
the original tests exercised that case. A new TypeScript retention
integration test seeded exactly that shape and caught it. Fixed by
reading the column as Option<String> and flattening the two
independently-nullable layers instead of assuming non-null. New
dedicated Rust test covers it directly.

7 new tests (4 Rust: trim/purge correctness and no-op cases, 1 Rust bug
regression test, 2 TypeScript bridge tests) plus 1 new integration test
proving retention purge works end-to-end through the real SQLite path.
Verified through the real built addon, with and without it present, plus
full e2e suite (10/10) and app unit suite (584/585, 1 intentional skip).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: voidstackloop

app/src/audit-log-store.test.ts

@@ -362,6 +362,26 @@ describe("audit-log-store", () => {
             settingsStore.saveSettings({ auditLogBackend: undefined });
             expect(auditLogStore.listEvents()).toHaveLength(0);
         });
+
+        it("purges expired events on write too, same as the JSON backend", async () => {
+            const { openAuditStore, migrateAuditLogFromJson } = await import("./native-sqlite-store");
+            const sqliteDbPath = path.join(app.getPath("userData"), "audit-log.sqlite3");
+
+            settingsStore.saveSettings({ auditLogBackend: "sqlite", auditLogRetentionDays: 30 });
+            openAuditStore(sqliteDbPath);
+            const old = new Date(Date.now() - 40 * 24 * 60 * 60 * 1000).toISOString(); // 40 days ago
+            migrateAuditLogFromJson(sqliteDbPath, JSON.stringify([{ id: "old-1", timestamp: old, actionCategory: "case-viewed" }]));
+
+            // Any write triggers the purge, per the same semantics as the
+            // JSON backend's "purges expired events on write too" test.
+            auditLogStore.recordEvent("case-created", { targetId: "new-write" });
+
+            const remaining = auditLogStore.listEvents();
+            expect(remaining.some((e) => e.id === "old-1")).toBe(false);
+            expect(remaining.some((e) => e.targetId === "new-write")).toBe(true);
+
+            settingsStore.saveSettings({ auditLogRetentionDays: undefined });
+        });
     });
 
     it("falls back to the JSON backend when sqlite is requested but the addon isn't available", () => {

app/src/audit-log-store.ts

@@ -12,6 +12,9 @@ import {
     migrateAuditLogFromJson,
     getLastAuditEventHash,
     listAuditEventsJson,
+    trimAuditEventsToCap,
+    purgeAuditEventsOlderThan,
+    auditEventCount as sqliteAuditEventCount,
 } from "./native-sqlite-store";
 import type { z } from "zod";
 
@@ -79,13 +82,16 @@ function writeAll(events: AuditEvent[]): void {
 // --- Optional SQLite backend (Settings → Audit & Privacy, experimental) ---
 //
 // Opt-in only; unset/"json" (the default) never touches any of this. See
-// docs/RUST_MIGRATION_ASSESSMENT.md for why this exists and what it
-// deliberately doesn't do yet: retention purging and the MAX_EVENTS soft
-// cap below are JSON-backend-only in this first slice — the SQLite backend
-// currently grows without a cap. That's a real, known gap (disk usage over
-// a long-lived install), not an oversight; SQLite inserts don't have the
-// JSON file's O(n²) growth problem regardless of table size, so it's a
-// lower-urgency follow-up than the bug that motivated the JSON-side fix.
+// docs/RUST_MIGRATION_ASSESSMENT.md. Retention purging and the MAX_EVENTS
+// cap are enforced here too (via trimAuditEventsToCap/
+// purgeAuditEventsOlderThan), reusing the same MAX_EVENTS/TRIM_BATCH
+// constants as the JSON backend — but unlike JSON, both are single indexed
+// SQLite DELETEs regardless of table size, so purging can run on every
+// write (matching the JSON backend's exact purge-on-write semantics) without
+// the O(n) cost that made the JSON backend's own cap soft in the first
+// place. The trim is still batched (TRIM_BATCH slack) purely to avoid an
+// extra DELETE on every single insert, not because a single trim is
+// expensive here.
 
 function sqliteDbPath(): string {
     return path.join(app.getPath("userData"), "audit-log.sqlite3");
@@ -151,6 +157,19 @@ function recordEventSqlite(dbPath: string, actionCategory: AuditActionCategory,
     // single new event, rather than a separate INSERT code path in Rust —
     // this event's id is always fresh (randomUUID()), so it always inserts.
     migrateAuditLogFromJson(dbPath, JSON.stringify([event]));
+
+    const retentionDays = getSettings().auditLogRetentionDays;
+    if (retentionDays && retentionDays > 0) {
+        const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000).toISOString();
+        purgeAuditEventsOlderThan(dbPath, cutoff);
+    }
+    // Soft cap, same shape as the JSON backend's (MAX_EVENTS + TRIM_BATCH
+    // slack) — only actually issues a DELETE once every TRIM_BATCH writes
+    // past the cap, not on every single one.
+    if (sqliteAuditEventCount(dbPath) > MAX_EVENTS + TRIM_BATCH) {
+        trimAuditEventsToCap(dbPath, MAX_EVENTS);
+    }
+
     return event;
 }
 

app/src/native-sqlite-store.test.ts

@@ -9,13 +9,16 @@ import {
     migrateAuditLogFromJson,
     auditEventCount,
     verifyAuditStore,
+    listAuditEventsJson,
+    trimAuditEventsToCap,
+    purgeAuditEventsOlderThan,
 } from "./native-sqlite-store";
 
 // Same addon-presence-varies-by-environment situation as
-// native-datastore.test.ts — see that file's comment. This module is inert
-// (see its own header comment): nothing in the running app calls it, so
-// these tests exist purely to prove the scaffold itself is correct ahead of
-// any future cutover, not to protect a live code path.
+// native-datastore.test.ts — see that file's comment. audit-log-store.ts
+// reaches this module only when a user has explicitly opted into the
+// experimental SQLite backend (Settings → Audit & Privacy); these tests
+// exercise the bridge directly, independent of that opt-in gate.
 const addonPresent = fs.existsSync(path.join(__dirname, "..", "native"));
 
 function tempDbPath(): string {
@@ -74,4 +77,49 @@ describe(`native-sqlite-store (addon ${addonPresent ? "present" : "unavailable"}
     (!addonPresent ? it : it.skip)("throws (rather than silently proceeding) when the addon isn't available", () => {
         expect(() => openAuditStore(tempDbPath())).toThrow();
     });
+
+    (addonPresent ? it : it.skip)("trimAuditEventsToCap keeps only the newest rows", () => {
+        const dbPath = tempDbPath();
+        try {
+            const events = Array.from({ length: 5 }, (_, i) => ({
+                id: `e${i}`,
+                timestamp: `2026-01-01T00:00:0${i}.000Z`,
+                actionCategory: "case-viewed",
+            }));
+            migrateAuditLogFromJson(dbPath, JSON.stringify(events));
+
+            const deleted = trimAuditEventsToCap(dbPath, 2);
+            expect(deleted).toBe(3);
+            expect(auditEventCount(dbPath)).toBe(2);
+
+            const remaining = JSON.parse(listAuditEventsJson(dbPath)) as { id: string }[];
+            expect(remaining.map((e) => e.id)).toEqual(["e3", "e4"]);
+        } finally {
+            fs.rmSync(dbPath, { force: true });
+            fs.rmSync(`${dbPath}-wal`, { force: true });
+            fs.rmSync(`${dbPath}-shm`, { force: true });
+        }
+    });
+
+    (addonPresent ? it : it.skip)("purgeAuditEventsOlderThan removes only expired rows", () => {
+        const dbPath = tempDbPath();
+        try {
+            const events = [
+                { id: "old", timestamp: "2020-01-01T00:00:00.000Z", actionCategory: "case-viewed" },
+                { id: "new", timestamp: "2030-01-01T00:00:00.000Z", actionCategory: "case-viewed" },
+            ];
+            migrateAuditLogFromJson(dbPath, JSON.stringify(events));
+
+            const deleted = purgeAuditEventsOlderThan(dbPath, "2025-01-01T00:00:00.000Z");
+            expect(deleted).toBe(1);
+            expect(auditEventCount(dbPath)).toBe(1);
+
+            const remaining = JSON.parse(listAuditEventsJson(dbPath)) as { id: string }[];
+            expect(remaining.map((e) => e.id)).toEqual(["new"]);
+        } finally {
+            fs.rmSync(dbPath, { force: true });
+            fs.rmSync(`${dbPath}-wal`, { force: true });
+            fs.rmSync(`${dbPath}-shm`, { force: true });
+        }
+    });
 });

app/src/native-sqlite-store.ts

@@ -21,6 +21,8 @@ interface NativeAddon {
     verifyAuditStore(dbPath: string): StoreIntegrityReport;
     getLastAuditEventHash(dbPath: string): string | null;
     listAuditEventsJson(dbPath: string): string;
+    trimAuditEventsToCap(dbPath: string, keepCount: number): number;
+    purgeAuditEventsOlderThan(dbPath: string, cutoffIso: string): number;
 }
 
 export interface MigrationReport {
@@ -106,3 +108,20 @@ export function getLastAuditEventHash(dbPath: string): string | null {
 export function listAuditEventsJson(dbPath: string): string {
     return getNativeAddon().listAuditEventsJson(dbPath);
 }
+
+/** Deletes the oldest rows beyond `keepCount`, returning how many were
+ * removed. A single indexed-adjacent DELETE regardless of table size —
+ * unlike the JSON backend's soft-cap trim, this doesn't need to be batched
+ * to stay cheap, though audit-log-store.ts still batches its *calls* to
+ * avoid running a DELETE on every single insert. */
+export function trimAuditEventsToCap(dbPath: string, keepCount: number): number {
+    return getNativeAddon().trimAuditEventsToCap(dbPath, keepCount);
+}
+
+/** Deletes every event older than `cutoffIso` (ISO-8601 UTC), returning how
+ * many were removed. Cheap enough (indexed DELETE) to call on every write
+ * when age-based retention is configured, matching the JSON backend's
+ * purge-on-every-write behavior without reintroducing an O(n) cost. */
+export function purgeAuditEventsOlderThan(dbPath: string, cutoffIso: string): number {
+    return getNativeAddon().purgeAuditEventsOlderThan(dbPath, cutoffIso);
+}

docs/RUST_MIGRATION_ASSESSMENT.md

@@ -282,18 +282,37 @@ results on both backends, clearAll clears both) plus a fallback test
 JSON — this one runs in every environment, addon or not). All verified
 through the real built addon, both with and without it present.
 
-**Known gap, explicitly not solved in this slice:** the SQLite backend has
-no retention purging or row cap yet — `MAX_EVENTS`/`TRIM_BATCH` are
-JSON-backend-only. This is a real, intentional scope cut, not an oversight:
-SQLite inserts don't have the JSON file's O(n²) growth problem regardless
-of table size, so unbounded row growth here is a disk-usage concern to
-address before this leaves "experimental," not the kind of performance
-cliff that motivated the JSON-side fix. No Settings UI toggle exists for
-`auditLogBackend` yet either — it's reachable today only by writing
-`settings.json` directly or programmatically, which is appropriate for an
-explicitly experimental first slice but would need a real UI (with the
-capability-report-driven "addon not available, staying on JSON" messaging
-this design already supports) before recommending it to anyone.
+**Both gaps flagged above have since been closed**, in two follow-up passes:
+
+- **Settings UI**: Audit & Privacy now has an "Audit log storage backend"
+  card — current-backend badge, a disabled state with the specific reason
+  when SQLite isn't available (via a new `audit:sqliteCapability` IPC
+  handler), and a switch button. New e2e spec drives the real app: create a
+  case on JSON, switch to SQLite, confirm the event migrated, switch back,
+  confirm it's still there.
+- **Retention/cap enforcement**: two more Rust functions,
+  `trim_audit_events_to_cap` and `purge_audit_events_older_than`, both
+  single indexed `DELETE`s — cheap regardless of table size, unlike the
+  JSON backend's full-file-rewrite equivalent, which is *why* the JSON
+  backend needed a soft cap with batching in the first place and this one
+  doesn't strictly need to (it still batches trim calls via the same
+  `TRIM_BATCH` constant, purely to avoid a `DELETE` on every single insert
+  — not because a single trim is expensive here). Age-based purge now runs
+  on every write when retention is configured, matching the JSON backend's
+  exact semantics without reintroducing an O(n) cost.
+
+**A real bug this surfaced, worth recording:** `get_last_audit_event_hash`
+crashed (`Invalid column type Null`) whenever the store's most recent row
+had a NULL `event_hash` — i.e. a legacy-shaped last event. None of the
+original Rust unit tests exercised that specific case (both events in the
+insertion-order test had hashes); a new TypeScript-level retention
+integration test seeded exactly that shape and caught it immediately. Fixed
+by reading the column as `Option<String>` and flattening the two
+independently-nullable layers (`.optional()` for "no rows at all" vs. the
+column itself being NULL) instead of assuming a non-null `String`. A
+dedicated Rust test (`last_event_hash_is_none_when_the_last_row_has_no_hash_column_value`)
+now covers this directly. Re-verified through the real built addon, in both
+the fallback and native states.
 
 **Explicitly not done, with reasons, per "stop and document the blocker"
 rather than half-finish:**
@@ -303,8 +322,6 @@ rather than half-finish:**
   for one store; repeating it for the others is real, separately-scoped
   work per store, not a mechanical copy-paste (their schemas and access
   patterns differ).
-- Retention/cap enforcement on the SQLite backend (see above).
-- A Settings UI toggle for `auditLogBackend` (see above).
 - Crypto vault, RAG index, filesystem capability layer, process supervisor,
   system-inspection rewrite, ingestion, safety-scanning engine, recommender
   inference — none started. Each is a substantial, independently-scoped