Export audit-trail tables to a dedicated folder before a destructive Reset

[DutchJaFO]

Background

Filed while planning #151 (ADR 014). #156 proposes that Reset stop selectively preserving any table
and instead drop the entire database and rebuild it in one step from the fresh-database baseline
script — the same path a brand-new install uses. That means, once #156 ships, a Reset will empty the
audit-trail tables (System_AuditEntries, System_ImportConflicts, System_ImportActions,
System_ChangeLog) completely, not just rows referencing entities that later changed id. Today these
four tables are excluded from Reset's drop list and survive it unconditionally — #156 removes that
survival entirely.

ADR 014 accepts this loss as the correct behaviour for Reset itself (Reset becomes, by design, "start
over completely"), on the condition that an operator who wants to keep the audit trail has a way to
do so first. This issue is that export mechanism — a genuine functional gap, not yet designed or
implemented.

What needs to be done

Design and implement an export step that writes the current contents of the four audit-trail tables
to a dedicated audit-history folder before a destructive Reset proceeds. Open design questions to
resolve during planning, not decided here:

• Trigger: either the export runs automatically and unconditionally as the first step of every
  Reset (before the backup DropAndRebuildAsync already takes), or it is a separate, standalone admin
  action the operator invokes beforehand. Not open for design: a request parameter letting the caller
  opt in/out of the export on a single Reset call. Per CLAUDE.md's "Endpoint side-effect policy
  (Single Responsibility)" (added while planning Should System_-prefixed provenance tables purge rows referencing Reset-wiped entities? #151/ADR 014), an endpoint must never grow a flag that
  changes what data survives the call — the choice is between "always happens" (a capture step, not a
  data-retention decision, so it doesn't violate the policy) and "a fully separate action," not a
  toggle on Reset itself.
• Format and location: what "a dedicated audit-history folder" means operationally — likely
  alongside the existing backup file mechanism (CreateBackup in DatabaseInitializer.cs) rather than
  a new persistence concept. Decide the file format (e.g. one JSON file per table, timestamped) and
  exact path under the data directory.
• Retention/pruning: an exported audit-history dump on every Reset could accumulate unbounded on a
  long-lived homelab install, similar to the pruning concern already raised in Import-table naming standardization + general import-file content provenance (FileResource / FileResourceLine) #227 for a different
  table. Decide whether this needs its own retention policy from day one or can defer.
• Scope of the four tables: confirm all four (System_AuditEntries, System_ImportConflicts,
  System_ImportActions, System_ChangeLog) export the same way, or whether any has a reason to be
  handled differently.

Dependency

Release gate on #156, not an implementation-order dependency. Per ADR 014, a tagged release must
never ship #156's destructive full-rebuild Reset without this export path already present in that same
release — but #249 and #156 can be designed, built, and merged in either order or in parallel.

Definition of done

• Design questions above resolved and recorded in a plan doc
• Export mechanism implemented and covered by tests
• docs/milestones/maintenance-milestone-v1.8.0/overview.md updated to reflect the release-gate
  relationship to Reset: use the fresh-database baseline script instead of drop-all-user-tables + replay #156
• Findings summarised in a closing comment

[DutchJaFO]

Shipped in v1.8.0 and confirmed still in place on current `main`.

Scope change (2026-08-05, before implementation started): redesigned from "automatic file-export step bolted onto Reset" to two on-demand HTTP endpoints (audit-trail bulk export) plus an auto-purge mechanism for the separate, transient conflict-resolution dataset. This resolved all of the original open design questions (trigger, format/location, retention/pruning) by making most of them moot — there's no accumulating export file to retain/prune, and no "when does the export run" question since retrieval is on-demand. `Import_Conflict` (originally one of the four tables in scope) was dropped entirely — confirmed dead code. Full reasoning in the plan doc's own "Scope changes" section.

#	Status	Requirement	Method	Verification
1	✅	Design decisions made and recorded	Live	Plan doc's "Decisions" section
2	✅	Audit-trail export returns both `Audit_Entry` and `Audit_Change` data for a date range, as a file	Endpoint test	`AdminAuditEndpointTests.ExportAudit_ReturnsBothTablesData`
3	✅	Date-range discovery endpoint returns the correct earliest/latest dates	Endpoint test	`AdminAuditEndpointTests.GetAuditDateRange_CombinesBothTables_ReturnsOverallEarliestAndLatest`
4	✅	Export request exceeding the row-count cap returns `422`, never a silently truncated file	Endpoint test	`AdminAuditEndpointTests.ExportAudit_CombinedRowCountExceedsCap_Returns422NotTruncatedFile`
5	✅	A seed batch reaching zero pending actions is auto-purged per the relevant per-origin setting	Unit test	`DatabaseInitializerTests.InitialiseAsync_AutoPurgeBundledTrue_FullyAppliedBundledBatch_PurgesImportActionRows` + 4 siblings
6	✅	`purgeOnSuccess=true` purges the batch's `Import_Action` rows only when zero pending actions remain	Endpoint + real-SQLite test	`ImportActionEndpointsTests.ApplyBatch_PurgeOnSuccessTrue_ForwardsTrueToService` + `SqliteImportActionServiceTests.ApplyBatchAsync_PurgeOnSuccessTrue_FullyApplied_PurgesImportActionRows`
7	✅	A purged batch fails `POST /import/actions/reverse` with a clear reason	Real-SQLite test	`SqliteImportActionServiceTests.ApplyBatchAsync_PurgeOnSuccessTrue_ThenReverseBatchAsync_ThrowsHasNoActionsException`
8	✅	`Import_Conflict` confirmed genuinely unreferenced	Live	`grep` sweep of `src/` — every hit is frozen migration history or the unrelated `ImportConflictEntry` DTO
9	✅	Full solution builds and tests pass	Live	0 warnings/errors, 3140 tests passed
10	✅	T1 verified	Live	Developer confirmed all admin/audit endpoints return correct status codes, no errors
11	✅	T2 verified	Live	`docs/smoke-tests.md` §31 — export/date-range/cap/auto-purge/`purgeOnSuccess` all confirmed against a real container

Retroactive close — this shipped in v1.8.0 but was never formally closed.