feat(audit): archive retention and superseded stale-archive cleanup (ScadaBridge#109)

Owner decisions recorded: the archive destination stays a directory/UNC
(no object-storage client; share + permissions named at enablement),
parquet-tools-only reading (no re-import), unsigned like the chain (#107).

AuditLog:Archive:RetentionDays (default 0 = never delete; else must exceed
AuditLog:RetentionDays, counted from the archived month's end) and
DeleteSupersededStaleArchives (default true) run after every purge tick.
A retried purge's stale Archived archive is deleted only when a later,
verifying, Purged archive of the same partition provably holds every row:
same prior anchor and the stale chain-end hash at its chain-end sequence
(row or tombstone), every unchained row present by EventId; otherwise it is
reported KeptStale. A sole copy left at Archived is never touched. Deletion
removes only the archive name's own three files in its folder, manifest
first, never a manifest-supplied path. `audit archive cleanup [--dry-run]`
= CleanupAuditArchives (Administrator).

AuditLogArchiveCleanupTests (MSSQL) cover retried purge, kept stale copy,
sole copy, retention and the path guard; each safety rule mutation-checked.
Follow-ups filed: #113, #114, #115.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 23:32:53 -05:00
parent c4d7ec9b96
commit b95ee5a658
26 changed files with 1099 additions and 26 deletions
@@ -66,6 +66,17 @@ public interface IAuditLogArchive
/// <returns>The verification result.</returns>
/// <exception cref="FileNotFoundException">No archive has that name.</exception>
Task<AuditArchiveVerificationResult> VerifyAsync(string name, CancellationToken ct = default);
/// <summary>
/// Archive cleanup (ScadaBridge#109): deletes superseded stale archives a retried purge left
/// behind (when <c>AuditLog:Archive:DeleteSupersededStaleArchives</c>), and archives past
/// <c>AuditLog:Archive:RetentionDays</c> (0 = never). Only ever deletes the three files of a
/// well-formed archive inside the configured directory, manifest first.
/// </summary>
/// <param name="dryRun">Report only; delete nothing.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>What was (or would be) deleted, and the stale archives kept.</returns>
Task<AuditArchiveCleanupResult> CleanupAsync(bool dryRun, CancellationToken ct = default);
}
/// <summary>
@@ -57,3 +57,12 @@ public record ListAuditArchivesCommand;
/// </summary>
/// <param name="Name">The archive name, as <c>audit archive list</c> reports it.</param>
public record VerifyAuditArchiveCommand(string Name);
/// <summary>
/// Runs the AuditLog archive cleanup (ScadaBridge#109) now: deletes superseded stale archives
/// a retried purge left behind and archives past <c>AuditLog:Archive:RetentionDays</c> — or,
/// with <paramref name="DryRun"/>, only reports what it would delete. The purge actor runs the
/// same pass after every purge tick. Administrator only (it deletes files).
/// </summary>
/// <param name="DryRun">Report only; delete nothing.</param>
public record CleanupAuditArchivesCommand(bool DryRun);
@@ -145,3 +145,41 @@ public sealed record AuditArchiveVerificationResult(
/// <param name="Enabled">Whether the retention purge is archiving partitions (<c>AuditLog:Archive:Enabled</c>).</param>
/// <param name="Archives">Every archive manifest, oldest partition first.</param>
public sealed record AuditArchiveListResult(bool Enabled, IReadOnlyList<AuditArchiveManifest> Archives);
/// <summary>What archive cleanup did (or, on a dry run, would do) with one archive (ScadaBridge#109).</summary>
[JsonConverter(typeof(JsonStringEnumConverter<AuditArchiveCleanupAction>))]
public enum AuditArchiveCleanupAction
{
/// <summary>
/// Deleted by retention: the archived month ended more than <c>AuditLog:Archive:RetentionDays</c>
/// ago, and the archive is purged (or its partition no longer holds rows).
/// </summary>
DeletedExpired,
/// <summary>
/// Deleted as a superseded stale archive: status <c>Archived</c> (its partition switch never
/// completed — a retried purge), and a LATER, verified, <c>Purged</c> archive of the same
/// partition provably holds every row it holds (same chain through its chain end, every
/// unchained row present by EventId).
/// </summary>
DeletedSuperseded,
/// <summary>
/// A stale <c>Archived</c> archive that was kept: no later purged archive provably covers it,
/// so it may be the only copy of some rows (see Detail).
/// </summary>
KeptStale,
}
/// <summary>One archive considered by cleanup.</summary>
/// <param name="Name">Archive name.</param>
/// <param name="Partition">Archived partition, <c>YYYY-MM</c>.</param>
/// <param name="Action">What was (or would be) done.</param>
/// <param name="Detail">Why.</param>
public sealed record AuditArchiveCleanupItem(string Name, string Partition, AuditArchiveCleanupAction Action, string Detail);
/// <summary>Result of an archive cleanup pass (ScadaBridge#109).</summary>
/// <param name="DryRun">True when nothing was deleted (the items say what would be).</param>
/// <param name="RetentionDays">The archive retention in force (0 = archives never expire).</param>
/// <param name="Items">The archives deleted (or that would be) and the stale ones kept.</param>
public sealed record AuditArchiveCleanupResult(bool DryRun, int RetentionDays, IReadOnlyList<AuditArchiveCleanupItem> Items);