perf(localdb): dereg API, O(1) backlog depth, byte-budget batching, prepare-once apply (0.2.0)

WP3.3 of the ScadaBridge architectural-review remediation. Six changes, all
wire-compatible with 0.1.x peers — no proto change, no lib_schema_version bump. The
on-disk bookkeeping schema goes to v2 and is upgraded in place when a file is opened.

DeregisterReplicated(table). There was no way to stop capturing once a file had been
registered, so a node that does not replicate kept paying three triggers inside every
write transaction, appending to an oplog nothing would ever drain. Drops the triggers and
prunes the table's oplog + row-version rows in one transaction; idempotent, and
deliberately usable on a table this process never registered, since stale triggers left by
an EARLIER build are the primary case. Deregistration must be symmetric across a pair, and
already is enforced: the handshake compares registered-table digests fail-closed, so a node
that drops a table its peer still replicates stops syncing loudly rather than diverging.

RegisterReplicated(table, baselineExistingRows: true). Closes the late-opt-in hole: the
snapshot streamer pages from __localdb_row_version, which only triggers populate, so a node
that started replicating LATE never sent its pre-existing rows — silently, forever. Seeding
alone would not have fixed it, because a node whose oplog starts at seq 1 presents no gap at
the handshake and is told it needs no snapshot; the seed therefore also flags needs_snapshot,
and the existing resync machinery carries the rows. The floor is HLC 0 stamped with this
node's id: every genuine HLC is a UTC millisecond shifted left 16 bits and so is strictly
greater, which makes a baselined row lose every comparison against a real remote write and
win only where the peer has no version of that key at all. Two nodes baselining the same key
both hold 0 and resolve by the node-id tie-break — convergent, and nothing better is
available for two rows of unordered antiquity. Opt-in, so the documented CDC contract is
unchanged unless asked. Pruning the ledger on deregister is safe precisely because
re-registration can re-baseline; the two APIs are a pair.

O(1) backlog depth. GetOplogDepth ran COUNT(*) over the entire unacked backlog, once a
minute from maintenance AND on every metrics scrape — a full scan of a million rows exactly
when a node is already behind. Now MAX(seq) - MAX(last_acked_seq, MIN(seq) - 1), floored at
0: three b-tree seeks, measured at 58 VM steps against 100,020 for the count on a 50k
backlog. Exact, because seq is AUTOINCREMENT and every prune path removes a prefix (ack
pruning by watermark, the row cap by count, the age cap by an HLC cutoff that rises with
seq). The MIN clamp is what keeps it exact after a cap prune has moved the horizon above a
stalled watermark — without it the caps would re-flag on every tick forever.

Byte-budget batching. MaxBatchSize was the only cap on an outbound message, which made it a
proxy for a byte budget that consumers had to tune against their widest row: ScadaBridge
pinned it to 16 because 70 KB config_json times the 500 default is ~35 MB against a 4 MB
gRPC limit. MaxBatchBytes (default 2 MB) now bounds delta and snapshot messages by summed
serialized size, with the row count demoted to a secondary cap. A row larger than the budget
is sent alone rather than stalling the stream on it. Since more, smaller messages would
otherwise mean more apply transactions and more acks, inbound delta batches and acks ALREADY
queued are coalesced — one transaction and one ack per burst, bounded by the sender's own
caps, and a no-op under a trickle.

LwwApplier prepares each statement once. It went through the generic transaction façade,
which builds a fresh SqliteCommand per call: three SQL parses per applied row, on the path
that drains a reconnect backlog. Statements are now held for the batch and rebound.

Dropped __localdb_oplog_hlc. It indexed (table_name, pk_json, hlc), which no query has ever
used — every oplog access path is by seq or a full hlc-predicate delete — while costing a
b-tree insert inside every captured consumer write.

184/184 tests pass (was 149). New coverage: schema upgrade drops the index and preserves
identity/watermarks/data, deregistration idempotency and trigger absence and cross-process
cleanup, baseline seeding at the floor with LWW safety proved through the real applier,
depth asserted equal to the counting query across every prune scenario plus a constant-time
assertion over a 200k backlog, byte-budget chunking including the one-giant-row edge on both
the delta and snapshot paths, prepare-once statement counting, and coalescing that must not
swallow the message that ends its run.

Version 0.2.0.

ZB.MOM.WW.LocalDb/src/ZB.MOM.WW.LocalDb.Replication/Internal/OplogStore.cs

@@ -70,12 +70,42 @@ internal sealed class OplogStore(ILocalDb db, ReplicationOptions options, Func<D
             "DELETE FROM __localdb_row_version WHERE is_tombstone = 1 AND tombstone_utc < @cutoff",
             new { cutoff = FormatUtc(_utcNow() - options.TombstoneRetention) }, ct);
 
-    /// <summary>Counts the unacked backlog: oplog entries above the peer's last-acked watermark.</summary>
+    /// <summary>
+    /// The unacked backlog — oplog entries above the peer's last-acked watermark — in O(1).
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>Why not <c>COUNT(*)</c>.</b> The obvious query walks every unacked row, and this value is
+    /// read once a minute by maintenance AND on every metrics scrape. A node whose peer has been
+    /// down for a day therefore pays a full scan of a million-row backlog, repeatedly, precisely
+    /// when it is already under stress.
+    /// </para>
+    /// <para>
+    /// <b>The formula.</b> <c>MAX(seq) - MAX(last_acked_seq, MIN(seq) - 1)</c>, floored at 0. Both
+    /// MIN and MAX over <c>seq</c> are single b-tree seeks (it is the rowid, and SQLite's min/max
+    /// optimization turns each into one seek), and the peer-state read is a one-row lookup — so the
+    /// whole thing is three seeks regardless of backlog size.
+    /// </para>
+    /// <para>
+    /// <b>Why it is exact.</b> <c>seq</c> is AUTOINCREMENT, so retained rows are a contiguous run
+    /// wherever nothing has punched a hole in the middle — and no ordinary path punches holes: ack
+    /// pruning deletes <c>seq &lt;= last_acked_seq</c> (a prefix), the row cap deletes below
+    /// <c>MAX(seq) - keep + 1</c> (a prefix), and the age cap deletes below an HLC cutoff, which is
+    /// a prefix because HLCs are stamped in seq order. Clamping the floor to <c>MIN(seq) - 1</c> is
+    /// what keeps the answer exact after a prune has moved the horizon above the ack watermark;
+    /// without it a cap-pruned oplog would report its whole seq range forever and re-flag the cap on
+    /// every tick.
+    /// </para>
+    /// <para>
+    /// <b>The one inexact case</b> is <c>ILocalDb.DeregisterReplicated</c>, which deletes one
+    /// table's rows from wherever they sit and so can leave holes. The estimate then over-reports by
+    /// at most the number of holes, until the watermark advances past them. Over-reporting is the
+    /// safe direction: it can only trigger a snapshot resync earlier, never suppress one.
+    /// </para>
+    /// </remarks>
     public async Task<long> GetOplogDepthAsync(CancellationToken ct = default)
     {
-        var rows = await db.QueryAsync(
-            "SELECT COUNT(*) FROM __localdb_oplog WHERE seq > (SELECT last_acked_seq FROM __localdb_peer_state WHERE id = 1)",
-            static r => r.GetInt64(0), null, ct);
+        var rows = await db.QueryAsync(DepthSql, static r => r.GetInt64(0), null, ct);
         return rows[0];
     }
 
@@ -84,7 +114,7 @@ internal sealed class OplogStore(ILocalDb db, ReplicationOptions options, Func<D
     /// metric-observation callbacks (gauge scrape / status poll); mirrors
     /// <see cref="GetOplogDepthAsync"/>'s query. Deliberate tradeoff: synchronous I/O on the
     /// metrics-collection thread is acceptable here because WAL-mode readers never block (or are
-    /// blocked by) writers, the COUNT is indexed-cheap, and the worst case is bounded by
+    /// blocked by) writers, the query is three b-tree seeks, and the worst case is bounded by
     /// <c>BusyTimeoutMs</c> — all at scrape frequency, not on any data path. May throw if the db
     /// is disposing — callers on the observation path swallow and drop the sample.
     /// </summary>
@@ -92,11 +122,18 @@ internal sealed class OplogStore(ILocalDb db, ReplicationOptions options, Func<D
     {
         using var conn = db.CreateConnection();
         using var cmd = conn.CreateCommand();
-        cmd.CommandText =
-            "SELECT COUNT(*) FROM __localdb_oplog WHERE seq > (SELECT last_acked_seq FROM __localdb_peer_state WHERE id = 1)";
+        cmd.CommandText = DepthSql;
         return (long)cmd.ExecuteScalar()!;
     }
 
+    // Both depth accessors run exactly this; keeping it in one place is what makes "mirrors the
+    // async query" a fact rather than a comment that can rot.
+    internal const string DepthSql =
+        "SELECT MAX(0, " +
+        "COALESCE((SELECT MAX(seq) FROM __localdb_oplog), 0) - " +
+        "MAX((SELECT last_acked_seq FROM __localdb_peer_state WHERE id = 1), " +
+        "COALESCE((SELECT MIN(seq) FROM __localdb_oplog), 1) - 1))";
+
     /// <summary>
     /// The highest seq this node has ever produced: the oplog's max, or — once acked rows have been
     /// pruned away — the ack watermark that pruned them. Nothing we emit can exceed it, so a peer
@@ -133,9 +170,9 @@ internal sealed class OplogStore(ILocalDb db, ReplicationOptions options, Func<D
         // Condition reads and prunes share the transaction so the decision cannot go stale (TOCTOU).
         await using var tx = await db.BeginTransactionAsync(ct);
 
-        var depth = (await tx.QueryAsync(
-            "SELECT COUNT(*) FROM __localdb_oplog WHERE seq > (SELECT last_acked_seq FROM __localdb_peer_state WHERE id = 1)",
-            static r => r.GetInt64(0), null, ct))[0];
+        // Same O(1) expression as GetOplogDepthAsync — the caps check is the per-minute reader that
+        // made the old COUNT(*) expensive in the first place.
+        var depth = (await tx.QueryAsync(DepthSql, static r => r.GetInt64(0), null, ct))[0];
         var overRows = depth > options.MaxOplogRows;
 
         var oldest = await tx.QueryAsync(