Skip to content
Chapter 7 · Decisions 7-13

Consolidate business persistence in the existing SQLite database

Settings, conversation sessions and Activity Timeline previously used JSON or JSONL alongside the durable Harness SQLite database. File replacement, metadata caches, listing budgets, in-memory deduplication and a legacy activity poller duplicated persistence concerns.

Schema v18 adds four focused tables to agent_harness.db: business_settings, business_sessions, business_activity and business_migrations. Existing Host-owned stores retain their validation. The original v18 design used bounded serialized session/message-ledger records with indexed summary metadata. ADR 0030 supersedes that storage choice: v30 normalizes retained messages and receipts and separates bounded read windows from durable retention. Settings and sanitized activity remain JSON payloads in SQLite rows. Session read/modify/write operations use one immediate transaction; activity insert, event-ID deduplication and retention share a transaction. Settings writes are atomic, while Credential Manager updates retain their existing compensation.

Each store imports legacy files once, in the same transaction as its migration marker. Sessions import all readable, valid documents without the old sidebar scan budget, preserving existing destination rows and respecting Harness session deletion tombstones; activity additionally imports legacy outboxes and .processing files. Cancellation and I/O errors roll back the import and leave it retryable. Malformed session documents and malformed/oversized activity lines remain excluded by the previous validation rules. Corrupt/oversized settings return defaults without marking migration complete; repair the legacy settings before retrying, or explicitly save replacement settings.

Legacy files remain untouched as backups. After a successful import, hand edits to these files are ignored, and deleting a session or clearing activity cannot reimport old records. No ongoing dual read/write path exists. Repair excluded session data through the supported session-import interface after correcting the document. There is no automatic downgrade/export to the old stores.

Stop the old Ru Host before upgrading so it cannot write to the legacy files after the new build has imported them. New-build stores coordinate writes through SQLite transactions.

API keys stay in Windows Credential Manager. Existing encrypted Harness payloads stay encrypted; this decision does not introduce database-wide encryption. Diagnostics, terminal output spools, runtime descriptors and small GUI preferences retain their existing file stores. The conversation outbox remains necessary for history/bootstrap/run-transition recovery; sharing a database alone does not make those operations one transaction. The unused activity-file poller is removed.

Back up the database through SQLite's backup API or stop all Ru Host processes before copying the database and any outstanding WAL. Copying only a live .db file is insufficient. Technical-log cleanup excludes legacy activity backups. ADR 0030 adds paged/search HTTP history routes and explicit maintenance commands; the Broker execution authority and SQLite ownership remain unchanged.