perf(security): move purge / dismiss / undismiss SQL onto a worker thread

[graydawnc]

What

Moves the six security mutation handlers (purge / dismiss / undismiss, single and bulk) onto a dedicated worker_thread so the main process event loop stays unblocked through the multi-second tail of bulk operations on a large archive.

Why

#346 fixed the original 60s freeze by collapsing bulk purge into a single transaction (60s → ~1.4s on the same 8k-finding test case). That was the right fix for the literal complaint in the issue, but the ~1.4s commit still ran synchronously on the main process — IPC, window dragging and the scan-worker's status-event forwarder all queued behind it. PR #346's description called this out as the next follow-up:

Move DB-heavy security mutations off the main process onto the existing scan-worker pattern, so even a sub-second purge does not cost a frame on the renderer.

This PR is that follow-up.

How

1. New worker thread (mutation-worker-thread.ts)

Mirrors the scan-worker-thread.ts shape. Opens its own better-sqlite3 handle with runMigrations: false (main migrated before spawning), shares the DB file via WAL. Handles six commands:

type MutationCommand =
  | { cmd: 'purgeFinding'; findingId: number }
  | { cmd: 'purgeFindings'; findingIds: number[] }
  | { cmd: 'purgeEverywhere'; kind, valueHash }
  | { cmd: 'dismissFinding'; findingId; scope }
  | { cmd: 'dismissFindings'; findingIds; scope }
  | { cmd: 'undismissFinding'; findingId }

Each per-mutation FindingsChange (from the core publish callback) streams back as a separate event-change message so the renderer's existing EVT_FINDINGS_CHANGED subscribers don't care whether the change came from a scan or a mutation.

2. Main-side proxy (mutation-worker-proxy.ts)

Spawns the worker, waits for ready, exposes a typed async API (proxy.purgeFindings(ids) → Promise<PurgeResult[]>, etc.). Forwards the worker's per-event stream onto a PubSub the IPC layer subscribes to with the same Stream.fromPubSub shape the scan worker already uses. Boot timeout, fatal-during-boot and posthumous-send rejection mirror the scan-worker-proxy contract.

3. Wire-error helpers (security/mutation-error-wire.ts)

Pure helpers for Effect.Exit → wire transformation. Extracted out of the worker because the first draft called Exit.causeOption(exit).value directly — that returns Cause<E>, not E, so every typed PurgeError was silently downgraded to { reason: 'unknown' } on the wire and the renderer's reason-keyed error branches were dead code. The correct chain is causeOption → Cause.failureOption. Now there's unwrapEffectFailure, flattenPurgeError, and exitToWireResult, plus 15 vitest cases pinning the contract. Verified to fail on the pre-fix shape (injected the buggy form locally, watched 4 tests go red).

4. IPC delegation (ipc/security.ts)

The six mutation handlers check for a mutationWorker prop and delegate when present; the existing in-process SQL stays as a fallback for the worker-boot-failure case (and unit tests that don't spin a real worker). A new daemon fiber forwards mutationWorker.changes → EVT_FINDINGS_CHANGED.

5. Boot / shutdown

bootMutationWorker() runs after bootScanWorker() so a scan-worker failure aborts the whole Security boot but a mutation-worker failure logs and continues (the fallback handles it). shutdownScanWorker() tears the mutation worker down alongside.

6. Build

One extra rollup input in electron.vite.config.ts for the new worker entry.

How it connects

• Same architecture as the scan worker — three persistent worker threads now (sync, scan, mutation), all sharing the DB via WAL. Where the scan worker has a queue + drain, the mutation worker is request/response with a reqId map; the read-heavy queries (lists, status snapshots) keep running on the main handle since they're cheap and don't block.
• The wire-error helper extraction is what lets the bug catch itself: the previous bug pattern was a one-line subtle Effect API misuse that only the regression tests would catch on a re-roll.

Verification

• New tests:
  • 2 in ipc/security.test.ts — a fake MutationWorkerProxy pinning the delegation, and the change-event forwarder
  • 15 in security/mutation-error-wire.test.ts — one per typed PurgeError reason, defect / interrupt / plain-Error degradation, the one-shot exitToWireResult wrapper
• All 31 existing IPC tests cover the in-process fallback path unchanged.
• Full app suite: 355 passed (340 prior + 15 new).
• App typecheck clean.
• Manual end-to-end on a real 7.9k-finding archive: 197 sessions had their previously-purged absolute-path findings restored via raw_file_mtime reset → syncer + scanner regenerated 7936 active absolute-path findings → single Purge all click → main process stayed responsive throughout (window drag and scroll unblocked) where pre-fix the same archive froze for ~1.4s. Content_text correctly masked, scan_purged_count per session aggregates correctly, all 7936 findings flipped state in one commit (state_changed_at = 2026-05-29T09:36:54.356Z).

Notes / non-goals

• Observability gap: the worker thread doesn't yet have its own OTel runtime, so security.purge.bulk spans don't reach the main process log. The scan worker has the same setup pattern (makeObservabilityRuntime); extending it here is straightforward follow-up.
• Pre-existing UX bug surfaced during testing (not introduced by this PR): when boot-time backfill and the post-syncAll backfill overlap, the renderer's progress bar appears to "rewind" because the second backfill calls resetBurst (sticky-max bypass) and the backfillTotal snaps to the smaller new-burst count. Will be addressed in a separate PR.