feat(localdb): one-time migrator for the pre-Phase-1 site databases

Task 6 of the LocalDb Phase 1 adoption plan. Copies site-tracking.db and
site_events.db into the consolidated database, then renames each source to
<name>.migrated.

Runs AFTER RegisterReplicated, deliberately: capture is trigger-based, so rows
inserted before registration would never enter the oplog and would never reach
the peer - silently. There is a test asserting migrated rows land in
__localdb_oplog, because every other test in the file would still pass with that
ordering reversed.

Idempotent twice over. Tracking rows keep their existing TEXT primary key, so
INSERT OR IGNORE dedupes naturally. Legacy events had autoincrement integer ids,
which the consolidated schema replaced with GUIDs; they get DETERMINISTIC ids of
the form mig-{NodeName}-{legacyId} rather than fresh GUIDs, so a migration that
crashes between commit and rename cannot duplicate history on the next boot. The
NodeName prefix keeps the two nodes of a pair from colliding on their independent
legacy id sequences. Both properties are covered, including an explicit
crash-window test that undoes the rename and re-runs.

All-or-nothing: the copy commits in one transaction and the rename happens only
afterwards, so a failure throws out of OnReady, fails host startup, and leaves
the legacy files untouched. Deviation from the plan: it specified
BeginTransactionAsync, but OnReady is a synchronous Action<ILocalDb>. A raw
transaction on a CreateConnection() connection gives identical atomicity and
identical trigger capture without blocking on async in a startup callback.

Legacy paths come from the OLD config keys and fall back to the CWD-relative code
defaults, because that is where the old code actually wrote them. Note this means
both legacy databases have always lived outside the mounted data volume and were
already discarded on every container recreate - so on the rig this migrator will
usually find nothing, which is a legitimate no-op rather than a failure. Phase 1
incidentally fixes that data-loss bug.

Non-failure cases are covered too: missing files, a legacy file with no such
table, and in-memory legacy connection strings from test/dev configs.

Verified: build 0 warnings; Host 316/316 (9 migrator tests new).

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts

src/ZB.MOM.WW.ScadaBridge.Host/SiteLocalDbLegacyMigrator.cs

@@ -0,0 +1,264 @@
+using Microsoft.Data.Sqlite;
+using Microsoft.Extensions.Configuration;
+using ZB.MOM.WW.LocalDb;
+
+namespace ZB.MOM.WW.ScadaBridge.Host;
+
+/// <summary>
+/// One-time copy of the pre-Phase-1 site databases (<c>site-tracking.db</c> and
+/// <c>site_events.db</c>) into the consolidated <c>ZB.MOM.WW.LocalDb</c> database.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Runs after <c>RegisterReplicated</c>, deliberately.</b> Capture is trigger-based, so
+/// rows inserted before registration would never enter the oplog and would never reach the
+/// peer. Migrating after registration means the migrated history replicates like any other
+/// write — which is the entire point of Phase 1.
+/// </para>
+/// <para>
+/// <b>Idempotent twice over.</b> Tracking rows carry the same TEXT primary key they always
+/// had, so <c>INSERT OR IGNORE</c> is naturally idempotent. Legacy events had autoincrement
+/// integer ids, which the consolidated schema replaced with GUIDs; they are given
+/// <i>deterministic</i> ids of the form <c>mig-{NodeName}-{legacyId}</c> rather than fresh
+/// GUIDs, so a migration that crashes and re-runs cannot duplicate events. The NodeName
+/// prefix keeps the two nodes of a pair from colliding on their independent legacy id
+/// sequences.
+/// </para>
+/// <para>
+/// <b>All-or-nothing.</b> The copy runs in one transaction and the legacy file is renamed
+/// to <c>&lt;name&gt;.migrated</c> only after commit. A failure throws out of
+/// <c>OnReady</c>, which fails host startup with the legacy files untouched — no
+/// half-migrated state to reason about. A second boot sees the renamed file and no-ops.
+/// </para>
+/// <para>
+/// <b>Finding nothing is the expected case on the docker rig.</b> Neither legacy config key
+/// is set in any rig appsettings, so both fall back to CWD-relative code defaults
+/// (<c>/app/site-tracking.db</c>, <c>/app/site_events.db</c>) that sit OUTSIDE the mounted
+/// data volume — meaning they were already being discarded on every container recreate.
+/// Phase 1 incidentally fixes that data-loss bug by consolidating into
+/// <c>/app/data/site-localdb.db</c>. A no-op here is a legitimate result, not a failure.
+/// </para>
+/// </remarks>
+public static class SiteLocalDbLegacyMigrator
+{
+    private const string MigratedSuffix = ".migrated";
+
+    /// <summary>Default legacy tracking connection string (<c>OperationTrackingOptions.ConnectionString</c>).</summary>
+    private const string DefaultTrackingConnectionString = "Data Source=site-tracking.db";
+
+    /// <summary>Default legacy event-log path (<c>SiteEventLogOptions.DatabasePath</c>).</summary>
+    private const string DefaultEventLogPath = "site_events.db";
+
+    /// <summary>
+    /// Copies any legacy site databases into <paramref name="db"/>, then renames them.
+    /// </summary>
+    /// <param name="db">The consolidated site database, with both tables already registered.</param>
+    /// <param name="config">Configuration supplying the legacy paths and the node name.</param>
+    public static void Migrate(ILocalDb db, IConfiguration config)
+    {
+        ArgumentNullException.ThrowIfNull(db);
+        ArgumentNullException.ThrowIfNull(config);
+
+        var nodeName = config["ScadaBridge:Node:NodeName"] ?? "unknown-node";
+
+        MigrateTracking(db, ResolveTrackingPath(config));
+        MigrateEvents(db, ResolveEventLogPath(config), nodeName);
+    }
+
+    /// <summary>
+    /// Resolves the legacy tracking database path from the OLD connection-string key,
+    /// falling back to the code default. Relative paths resolve against the process working
+    /// directory — NOT the data volume — because that is where the old code actually put them.
+    /// </summary>
+    internal static string ResolveTrackingPath(IConfiguration config)
+    {
+        var connectionString =
+            config["ScadaBridge:OperationTracking:ConnectionString"] ?? DefaultTrackingConnectionString;
+
+        string dataSource;
+        try
+        {
+            dataSource = new SqliteConnectionStringBuilder(connectionString).DataSource;
+        }
+        catch (ArgumentException)
+        {
+            // An unparseable legacy connection string means there is nothing to migrate
+            // from. Do not fail the host over a stale key we are about to stop reading.
+            return string.Empty;
+        }
+
+        // In-memory legacy databases (test/dev configurations) have nothing durable to
+        // migrate, and Path.GetFullPath on them would produce nonsense.
+        if (string.IsNullOrWhiteSpace(dataSource) ||
+            dataSource.Equals(":memory:", StringComparison.OrdinalIgnoreCase) ||
+            dataSource.StartsWith("file:", StringComparison.OrdinalIgnoreCase))
+        {
+            return string.Empty;
+        }
+
+        return Path.GetFullPath(dataSource);
+    }
+
+    /// <summary>Resolves the legacy event-log path from the OLD key, falling back to the code default.</summary>
+    internal static string ResolveEventLogPath(IConfiguration config)
+    {
+        var path = config["ScadaBridge:SiteEventLog:DatabasePath"] ?? DefaultEventLogPath;
+
+        if (string.IsNullOrWhiteSpace(path) ||
+            path.Equals(":memory:", StringComparison.OrdinalIgnoreCase))
+        {
+            return string.Empty;
+        }
+
+        return Path.GetFullPath(path);
+    }
+
+    private static void MigrateTracking(ILocalDb db, string legacyPath)
+    {
+        if (!ShouldMigrate(legacyPath)) return;
+
+        var rows = ReadAll(
+            legacyPath,
+            """
+            SELECT TrackedOperationId, Kind, TargetSummary, Status,
+                   RetryCount, LastError, HttpStatus,
+                   CreatedAtUtc, UpdatedAtUtc, TerminalAtUtc,
+                   SourceInstanceId, SourceScript, SourceNode
+            FROM   OperationTracking;
+            """,
+            expectedColumns: 13);
+
+        // A legacy file with no OperationTracking table at all reads as "nothing to do";
+        // it still gets renamed so the probe does not repeat on every boot.
+        if (rows is not null)
+        {
+            using var connection = db.CreateConnection();
+            using var transaction = connection.BeginTransaction();
+
+            foreach (var row in rows)
+            {
+                using var cmd = connection.CreateCommand();
+                cmd.Transaction = transaction;
+                cmd.CommandText = """
+                    INSERT OR IGNORE INTO OperationTracking (
+                        TrackedOperationId, Kind, TargetSummary, Status,
+                        RetryCount, LastError, HttpStatus,
+                        CreatedAtUtc, UpdatedAtUtc, TerminalAtUtc,
+                        SourceInstanceId, SourceScript, SourceNode
+                    ) VALUES (
+                        $p0, $p1, $p2, $p3, $p4, $p5, $p6,
+                        $p7, $p8, $p9, $p10, $p11, $p12
+                    );
+                    """;
+                Bind(cmd, row);
+                cmd.ExecuteNonQuery();
+            }
+
+            transaction.Commit();
+        }
+
+        MarkMigrated(legacyPath);
+    }
+
+    private static void MigrateEvents(ILocalDb db, string legacyPath, string nodeName)
+    {
+        if (!ShouldMigrate(legacyPath)) return;
+
+        var rows = ReadAll(
+            legacyPath,
+            """
+            SELECT id, timestamp, event_type, severity, instance_id, source, message, details
+            FROM   site_events;
+            """,
+            expectedColumns: 8);
+
+        if (rows is not null)
+        {
+            using var connection = db.CreateConnection();
+            using var transaction = connection.BeginTransaction();
+
+            foreach (var row in rows)
+            {
+                using var cmd = connection.CreateCommand();
+                cmd.Transaction = transaction;
+                cmd.CommandText = """
+                    INSERT OR IGNORE INTO site_events (
+                        id, timestamp, event_type, severity, instance_id, source, message, details
+                    ) VALUES (
+                        $id, $p1, $p2, $p3, $p4, $p5, $p6, $p7
+                    );
+                    """;
+
+                // Deterministic id, NOT a fresh GUID: a crashed-then-rerun migration must
+                // not duplicate events, and INSERT OR IGNORE can only dedupe on a stable key.
+                cmd.Parameters.AddWithValue("$id", $"mig-{nodeName}-{row[0] ?? "null"}");
+                for (var i = 1; i < row.Length; i++)
+                    cmd.Parameters.AddWithValue($"$p{i}", row[i] ?? (object)DBNull.Value);
+
+                cmd.ExecuteNonQuery();
+            }
+
+            transaction.Commit();
+        }
+
+        MarkMigrated(legacyPath);
+    }
+
+    /// <summary>True when there is a legacy file present that has not already been migrated.</summary>
+    private static bool ShouldMigrate(string legacyPath)
+        => !string.IsNullOrEmpty(legacyPath)
+           && File.Exists(legacyPath)
+           && !File.Exists(legacyPath + MigratedSuffix);
+
+    /// <summary>
+    /// Reads every row of <paramref name="sql"/> from the legacy file, or null when the
+    /// table does not exist (an old file predating the table is not an error).
+    /// </summary>
+    private static List<object?[]>? ReadAll(string legacyPath, string sql, int expectedColumns)
+    {
+        using var connection = new SqliteConnection($"Data Source={legacyPath};Mode=ReadOnly");
+        connection.Open();
+
+        using var cmd = connection.CreateCommand();
+        cmd.CommandText = sql;
+
+        SqliteDataReader reader;
+        try
+        {
+            reader = cmd.ExecuteReader();
+        }
+        catch (SqliteException)
+        {
+            // "no such table" / "no such column" — a legacy file from before this table
+            // existed, or a shape we do not recognise. Nothing to copy.
+            return null;
+        }
+
+        var rows = new List<object?[]>();
+        using (reader)
+        {
+            while (reader.Read())
+            {
+                var row = new object?[expectedColumns];
+                for (var i = 0; i < expectedColumns; i++)
+                    row[i] = reader.IsDBNull(i) ? null : reader.GetValue(i);
+                rows.Add(row);
+            }
+        }
+
+        return rows;
+    }
+
+    private static void Bind(SqliteCommand cmd, object?[] row)
+    {
+        for (var i = 0; i < row.Length; i++)
+            cmd.Parameters.AddWithValue($"$p{i}", row[i] ?? (object)DBNull.Value);
+    }
+
+    /// <summary>
+    /// Renames the legacy file so a later boot skips it. Done only after the copy has
+    /// committed; the file is kept rather than deleted so an operator can still inspect it.
+    /// </summary>
+    private static void MarkMigrated(string legacyPath)
+        => File.Move(legacyPath, legacyPath + MigratedSuffix);
+}

src/ZB.MOM.WW.ScadaBridge.Host/SiteLocalDbSetup.cs

@@ -1,3 +1,4 @@
+using Microsoft.Extensions.Configuration;
 using ZB.MOM.WW.LocalDb;
 using ZB.MOM.WW.ScadaBridge.SiteEventLogging;
 using ZB.MOM.WW.ScadaBridge.SiteRuntime.Tracking;
@@ -29,12 +30,15 @@ namespace ZB.MOM.WW.ScadaBridge.Host;
 public static class SiteLocalDbSetup
 {
     /// <summary>
-    /// Creates the site node's replicated tables and opts them into change capture.
+    /// Creates the site node's replicated tables, opts them into change capture, and
+    /// migrates any pre-Phase-1 databases in.
     /// </summary>
     /// <param name="db">The LocalDb instance being initialized.</param>
-    public static void OnReady(ILocalDb db)
+    /// <param name="config">Configuration, for the legacy migrator's old path keys and node name.</param>
+    public static void OnReady(ILocalDb db, IConfiguration config)
     {
         ArgumentNullException.ThrowIfNull(db);
+        ArgumentNullException.ThrowIfNull(config);
 
         using (var connection = db.CreateConnection())
         {
@@ -47,5 +51,9 @@ public static class SiteLocalDbSetup
         // capture). Registration is idempotent and installs the capture triggers.
         db.RegisterReplicated("OperationTracking");
         db.RegisterReplicated("site_events");
+
+        // AFTER registration, so migrated rows enter the oplog and reach the peer like
+        // any other write. Before it, they would be invisible to replication forever.
+        SiteLocalDbLegacyMigrator.Migrate(db, config);
     }
 }

src/ZB.MOM.WW.ScadaBridge.Host/SiteServiceRegistration.cs

@@ -60,7 +60,7 @@ public static class SiteServiceRegistration
         // initiator idles.
         //
         // Design: scadaproj docs/plans/2026-07-19-scadabridge-localdb-design.md
-        services.AddZbLocalDb(config, SiteLocalDbSetup.OnReady);
+        services.AddZbLocalDb(config, db => SiteLocalDbSetup.OnReady(db, config));
 
         // The replication engine, likewise unconditional but INERT by default: with no
         // LocalDb:Replication:PeerAddress the initiating SyncBackgroundService starts and