feat(audit): hash-chain cutoff - chain only rows written from first enablement, no backlog (#139)

Owner decision on #107 (2026-11-13): enabling AuditLog:HashChain must not
chain the historical backlog. main chained every unchained row oldest-first.

- The first chaining pass on a pristine database (no head, no chained row)
  writes a chain-start anchor: AuditLogChainTombstone (cutoff month,
  ChainSeq 0), PurgedAtUtc = DB SYSUTCDATETIME(), RowHash =
  SHA-256("ScadaBridge.AuditLog.ChainCutoff.v1" || YYYY-MM || ticks).
  Written once under the exclusive chain lock, so both centrals agree
  whatever their clocks/config. No migration: existing table + grants.
- Only rows with OccurredAtUtc >= cutoff are chained. The anchor hash is
  the cutoff month's genesis, binding the cutoff into the chain.
- AuditLog:HashChain:ChainBacklog (default false) restores chain-everything,
  read only on the very first enablement. Legacy chains (heads, no anchor)
  keep chaining everything.
- verify-chain splits unchained rows into UnchainedRows vs PreCutoffRows
  (+ ChainFromUtc); new breaks ChainedBeforeCutoff (row re-dated before the
  cutoff, or cutoff moved forward) and CutoffAnchorInvalid (anchor hash /
  month / multiplicity). Archive verify uses the anchor from its own
  tombstone file or the DB.
- Partition switch-out keeps the anchor (deletes ChainSeq > 0 only); the
  head store / export / verify-heads tombstone count excludes it.
- CLI verify-chain table prints Chain from + Pre-cutoff rows.

Tests: AuditLogHashChainCutoffTests (7, MSSQL), 6 verifier unit tests,
service/CLI/management wire tests; 9 mutations all killed.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-13 03:14:03 -05:00
parent 712c5117ee
commit 52da02a76a
21 changed files with 1208 additions and 49 deletions
@@ -31,10 +31,22 @@ public interface IAuditLogHashChain
/// Returns immediately with <see cref="AuditChainBatchResult.LockBusy"/> set when another
/// chainer holds the chain lock.
/// </summary>
/// <remarks>
/// <b>Chain start (ScadaBridge#139).</b> On a pristine database (nothing ever chained) and
/// with <paramref name="chainBacklog"/> false, the first pass records a chain-start anchor
/// at the database's current UTC time; from then on only rows dated at or after it are
/// chained, whatever either node passes later. With <paramref name="chainBacklog"/> true on
/// that first pass, no anchor is written and every row is chained, oldest month first. A
/// database that already has a chain and no anchor keeps chaining every row.
/// </remarks>
/// <param name="batchSize">Maximum rows to chain in this pass.</param>
/// <param name="chainBacklog">
/// Only consulted on a pristine database: true chains the historical backlog instead of
/// starting the chain now.
/// </param>
/// <param name="ct">Cancellation token.</param>
/// <returns>How many rows were chained, and whether the lock was busy.</returns>
Task<AuditChainBatchResult> ChainPendingAsync(int batchSize, CancellationToken ct = default);
Task<AuditChainBatchResult> ChainPendingAsync(int batchSize, bool chainBacklog = false, CancellationToken ct = default);
/// <summary>
/// Verifies one month's chain end to end and reports the first break.
@@ -46,6 +46,20 @@ public enum AuditChainBreakKind
/// deleted from the tail, or the head itself was altered.
/// </summary>
HeadMismatch,
/// <summary>
/// A chained row is dated before the chain cutoff (ScadaBridge#139). Rows before the cutoff
/// are never chained, so the row's <c>OccurredAtUtc</c> was moved back (to hide it among the
/// unprotected pre-cutoff rows) or the cutoff itself was moved forward.
/// </summary>
ChainedBeforeCutoff,
/// <summary>
/// The chain-start (cutoff) anchor is inconsistent (ScadaBridge#139): its stored hash does not
/// match its cutoff, it sits in the wrong month, or more than one anchor exists. The cutoff
/// that decides which rows are in scope cannot be trusted.
/// </summary>
CutoffAnchorInvalid,
}
/// <summary>
@@ -80,10 +94,20 @@ public sealed record AuditChainBreak(
/// </param>
/// <param name="HeadSeq">The last sequence number the chain head records, or null when the month has no head.</param>
/// <param name="UnchainedRows">
/// Rows in the month the chaining job has not reached yet (written since the last tick, or
/// written while chaining was disabled). They are not covered by the chain.
/// Rows in the month, at or after the chain cutoff, that the chaining job has not reached yet
/// (written since the last tick, or written while chaining was disabled). They are not covered
/// by the chain yet.
/// </param>
/// <param name="FirstBreak">The first break, or null when <see cref="Status"/> is not <see cref="AuditChainStatus.Broken"/>.</param>
/// <param name="PreCutoffRows">
/// Rows in the month dated before the chain cutoff (ScadaBridge#139). They are out of scope by
/// design — the chain covers only rows written from its first enablement on — so they are
/// never chained and never a break. Zero when the chain has no cutoff.
/// </param>
/// <param name="ChainFromUtc">
/// The chain cutoff: the instant the chain was first enabled without backlog chaining. Null
/// when the chain covers the whole table (legacy / <c>ChainBacklog</c> enablement).
/// </param>
public sealed record AuditChainVerificationResult(
string Partition,
AuditChainStatus Status,
@@ -92,7 +116,9 @@ public sealed record AuditChainVerificationResult(
long? PurgedThroughSeq,
long? HeadSeq,
long UnchainedRows,
AuditChainBreak? FirstBreak);
AuditChainBreak? FirstBreak,
long PreCutoffRows = 0,
DateTime? ChainFromUtc = null);
/// <summary>Outcome of one chaining pass over unchained AuditLog rows.</summary>
/// <param name="RowsChained">Rows linked into a chain by this pass.</param>