refactor(db): migrate cover letter history

Move append-only cover letter revisions into an additive provider-aware migration. Preserve manual and AI text, source metadata, ordering, and application cascade semantics.

JobTrackerApi.Tests/MigrationChainTests.cs

@@ -116,6 +116,7 @@ public sealed class MigrationChainTests
         Assert.Contains("CREATE TABLE IF NOT EXISTS `CvVariants`", script, StringComparison.Ordinal);
         Assert.Contains("CREATE TABLE IF NOT EXISTS `CvVariantVersions`", script, StringComparison.Ordinal);
         Assert.Contains("CREATE TABLE IF NOT EXISTS `ApplicationChecklistItems`", script, StringComparison.Ordinal);
+        Assert.Contains("CREATE TABLE IF NOT EXISTS `CoverLetterVersions`", script, StringComparison.Ordinal);
         Assert.Contains("`UiLanguage` varchar(16)", script, StringComparison.Ordinal);
         Assert.All(
             Regex.Matches(script, "CONSTRAINT `([^`]+)`").Select(match => match.Groups[1].Value),
@@ -766,6 +767,59 @@ public sealed class MigrationChainTests
         Assert.Empty(await db.Database.GetPendingMigrationsAsync());
     }
 
+    [Fact]
+    public async Task Cover_letter_version_adoption_preserves_manual_and_ai_history()
+    {
+        await using var connection = new SqliteConnection("Data Source=:memory:");
+        await connection.OpenAsync();
+        await using var db = Context(connection);
+        var migrator = db.GetService<IMigrator>();
+        await migrator.MigrateAsync("20260830130000_AdoptApplicationChecklistSchema");
+        await ExecuteAsync(connection, """
+            INSERT INTO Companies (Name) VALUES ('Fixture company');
+            INSERT INTO JobApplications
+                (CompanyId, JobTitle, DateApplied, SavedAt, Status, ResponseReceived, OwnerUserId,
+                 HasResume, HasCoverLetter, HasPortfolio, HasOtherAttachment, IsDeleted)
+            VALUES
+                (1, 'Fixture role', '2026-08-01T09:00:00', '2026-07-20T09:00:00',
+                 'Applied', 0, 'owner-fixture', 0, 0, 0, 0, 0);
+            CREATE TABLE "CoverLetterVersions" (
+                "Id" INTEGER NOT NULL CONSTRAINT "PK_CoverLetterVersions" PRIMARY KEY AUTOINCREMENT,
+                "OwnerUserId" TEXT NOT NULL, "JobApplicationId" INTEGER NOT NULL,
+                "Version" INTEGER NOT NULL, "Text" TEXT NOT NULL, "Source" TEXT NOT NULL,
+                "AiAction" TEXT NULL, "CreatedAtUtc" TEXT NOT NULL,
+                CONSTRAINT "FK_CoverLetterVersions_JobApplications_JobApplicationId"
+                    FOREIGN KEY ("JobApplicationId") REFERENCES "JobApplications" ("Id") ON DELETE CASCADE
+            );
+            INSERT INTO "CoverLetterVersions"
+                ("OwnerUserId", "JobApplicationId", "Version", "Text", "Source", "AiAction", "CreatedAtUtc")
+            VALUES
+                ('owner-fixture', 1, 1, 'Manual first draft', 'manual', NULL,
+                 '2026-08-30T09:00:00+00:00'),
+                ('owner-fixture', 1, 2, 'Shorter approved draft', 'ai', 'shorten',
+                 '2026-08-30T09:10:00+00:00');
+            """);
+
+        await migrator.MigrateAsync();
+        Assert.Equal("Manual first draft", await ScalarAsync<string>(connection,
+            "SELECT Text FROM CoverLetterVersions WHERE Version = 1;"));
+        Assert.Equal("shorten", await ScalarAsync<string>(connection,
+            "SELECT AiAction FROM CoverLetterVersions WHERE Version = 2;"));
+
+        await migrator.MigrateAsync("20260830130000_AdoptApplicationChecklistSchema");
+        Assert.Equal(2L, await ScalarAsync<long>(connection,
+            "SELECT COUNT(*) FROM CoverLetterVersions WHERE JobApplicationId = 1;"));
+        await migrator.MigrateAsync();
+        Assert.Equal(1L, await ScalarAsync<long>(connection, """
+            SELECT COUNT(*) FROM sqlite_master
+            WHERE type = 'index' AND name = 'IX_CoverLetterVersions_Owner_Job_Version';
+            """));
+
+        await ExecuteAsync(connection, "DELETE FROM JobApplications WHERE Id = 1;");
+        Assert.Equal(0L, await ScalarAsync<long>(connection, "SELECT COUNT(*) FROM CoverLetterVersions;"));
+        Assert.Empty(await db.Database.GetPendingMigrationsAsync());
+    }
+
     private static JobTrackerContext Context(SqliteConnection connection)
     {
         var currentUser = new Mock<ICurrentUserService>();

JobTrackerApi/Migrations/20260830131000_AdoptCoverLetterVersionSchema.cs

@@ -0,0 +1,64 @@
+using System;
+using JobTrackerApi.Data;
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace JobTrackerApi.Migrations;
+
+/// <summary>
+/// Moves append-only cover-letter revision history into migration ownership without replacing
+/// manually edited or AI-approved document versions.
+/// </summary>
+[DbContext(typeof(JobTrackerContext))]
+[Migration("20260830131000_AdoptCoverLetterVersionSchema")]
+public sealed class AdoptCoverLetterVersionSchema : Migration
+{
+    protected override void Up(MigrationBuilder migrationBuilder)
+    {
+        if (ActiveProvider.Contains("MySql", StringComparison.OrdinalIgnoreCase))
+        {
+            migrationBuilder.Sql("""
+                CREATE TABLE IF NOT EXISTS `CoverLetterVersions` (
+                    `Id` int NOT NULL AUTO_INCREMENT,
+                    `OwnerUserId` varchar(255) NOT NULL,
+                    `JobApplicationId` int NOT NULL,
+                    `Version` int NOT NULL,
+                    `Text` longtext NOT NULL,
+                    `Source` varchar(32) NOT NULL,
+                    `AiAction` varchar(32) NULL,
+                    `CreatedAtUtc` datetime(6) NOT NULL,
+                    PRIMARY KEY (`Id`),
+                    CONSTRAINT `FK_CoverLetterVersions_JobApplications_JobApplicationId`
+                        FOREIGN KEY (`JobApplicationId`) REFERENCES `JobApplications` (`Id`) ON DELETE CASCADE
+                ) CHARACTER SET=utf8mb4;
+                CREATE INDEX IF NOT EXISTS `IX_CoverLetterVersions_Owner_Job_Version`
+                    ON `CoverLetterVersions` (`OwnerUserId`, `JobApplicationId`, `Version`);
+                """);
+            return;
+        }
+
+        migrationBuilder.Sql("""
+            CREATE TABLE IF NOT EXISTS "CoverLetterVersions" (
+                "Id" INTEGER NOT NULL CONSTRAINT "PK_CoverLetterVersions" PRIMARY KEY AUTOINCREMENT,
+                "OwnerUserId" TEXT NOT NULL,
+                "JobApplicationId" INTEGER NOT NULL,
+                "Version" INTEGER NOT NULL,
+                "Text" TEXT NOT NULL,
+                "Source" TEXT NOT NULL,
+                "AiAction" TEXT NULL,
+                "CreatedAtUtc" TEXT NOT NULL,
+                CONSTRAINT "FK_CoverLetterVersions_JobApplications_JobApplicationId"
+                    FOREIGN KEY ("JobApplicationId") REFERENCES "JobApplications" ("Id") ON DELETE CASCADE
+            );
+            CREATE INDEX IF NOT EXISTS "IX_CoverLetterVersions_Owner_Job_Version"
+                ON "CoverLetterVersions" ("OwnerUserId", "JobApplicationId", "Version");
+            """);
+    }
+
+    protected override void Down(MigrationBuilder migrationBuilder)
+    {
+        // Preserve recoverable document history created before migration ownership.
+    }
+}

JobTrackerApi/Models/CoverLetterVersion.cs

@@ -7,7 +7,7 @@ namespace JobTrackerApi.Models;
 // to be, so an AI rewrite or a bad edit is never destructive. Mirrors CvVariantVersion: restore
 // re-saves an old snapshot as a new version rather than rewinding.
 //
-// Reconciler-owned (docs/infrastructure/database-ownership.md) — its migration is a no-op.
+// Migration-owned; the historical no-op is followed by an additive provider-aware adoption.
 public sealed class CoverLetterVersion
 {
     public int Id { get; set; }

JobTrackerApi/Services/StartupInitializationExtensions.cs

@@ -712,25 +712,6 @@ public static class StartupInitializationExtensions
                     EnsureColumn(c, "AiInteractions", "EstimatedTokenCount", "ALTER TABLE AiInteractions ADD COLUMN EstimatedTokenCount INTEGER NOT NULL DEFAULT 0;");
                 }
 
-                // Phase 5.4: append-only cover letter history.
-                static void EnsureCoverLetterVersionsTable(DbConnection c)
-                {
-                    Exec(c, """
-        CREATE TABLE IF NOT EXISTS "CoverLetterVersions" (
-            "Id" INTEGER NOT NULL CONSTRAINT "PK_CoverLetterVersions" PRIMARY KEY AUTOINCREMENT,
-            "OwnerUserId" TEXT NOT NULL,
-            "JobApplicationId" INTEGER NOT NULL,
-            "Version" INTEGER NOT NULL,
-            "Text" TEXT NOT NULL,
-            "Source" TEXT NOT NULL,
-            "AiAction" TEXT NULL,
-            "CreatedAtUtc" TEXT NOT NULL,
-            CONSTRAINT "FK_CoverLetterVersions_JobApplications_JobApplicationId" FOREIGN KEY ("JobApplicationId") REFERENCES "JobApplications" ("Id") ON DELETE CASCADE
-        );
-        """);
-                    Exec(c, """CREATE INDEX IF NOT EXISTS "IX_CoverLetterVersions_Owner_Job_Version" ON "CoverLetterVersions" ("OwnerUserId", "JobApplicationId", "Version");""");
-                }
-
                 // Phase 5.5: user-owned interview preparation (not the AI cache InterviewPrepNote).
                 static void EnsureInterviewPrepItemsTable(DbConnection c)
                 {
@@ -756,7 +737,6 @@ public static class StartupInitializationExtensions
                 ReconcileGmailConnectionColumns(conn);
                 EnsureCareerProfileTables(conn);
                 ReconcileAiInteractionUsageColumns(conn);
-                EnsureCoverLetterVersionsTable(conn);
                 EnsureInterviewPrepItemsTable(conn);
 
                 // Once the base app tables exist, provision this reconciler-owned schema set and
@@ -1151,24 +1131,6 @@ public static class StartupInitializationExtensions
                     DropMalformedMySqlTable(conn, "CoverLetterVersions", "CreatedAtUtc", "datetime");
                     DropMalformedMySqlTable(conn, "InterviewPrepItems", "CreatedAtUtc", "datetime");
 
-                    if (!HasMySqlTable(conn, "CoverLetterVersions") && HasMySqlTable(conn, "JobApplications"))
-                    {
-                        using var cmd = conn.CreateCommand();
-                        cmd.CommandText = @"CREATE TABLE IF NOT EXISTS `CoverLetterVersions` (
-        `Id` int NOT NULL AUTO_INCREMENT,
-        `OwnerUserId` varchar(255) NOT NULL,
-        `JobApplicationId` int NOT NULL,
-        `Version` int NOT NULL,
-        `Text` longtext NOT NULL,
-        `Source` varchar(32) NOT NULL,
-        `AiAction` varchar(32) NULL,
-        `CreatedAtUtc` datetime(6) NOT NULL,
-        PRIMARY KEY (`Id`),
-        CONSTRAINT `FK_CoverLetterVersions_JobApplications_JobApplicationId` FOREIGN KEY (`JobApplicationId`) REFERENCES `JobApplications` (`Id`) ON DELETE CASCADE
-        );";
-                        cmd.ExecuteNonQuery();
-                    }
-
                     if (!HasMySqlTable(conn, "InterviewPrepItems") && HasMySqlTable(conn, "JobApplications"))
                     {
                         using var cmd = conn.CreateCommand();

JobTrackerApi/Services/StartupSchemaOwnership.cs

@@ -18,6 +18,7 @@ internal static class StartupSchemaOwnership
         "Attachments",
         "Companies",
         "Correspondences",
+        "CoverLetterVersions",
         "CvExtractionRuns",
         "CvUploadArtifacts",
         "CvVariants",
@@ -60,7 +61,6 @@ internal static class StartupSchemaOwnership
         "CareerProfileVersions",
         "CareerProjects",
         "CareerSkills",
-        "CoverLetterVersions",
         "InterviewPrepItems",
     };
 

docs/audits/audit-remediation-backlog.md

@@ -558,7 +558,7 @@ SEC-008 implements the same durable state machine with `<final>.uploading` and `
 
 ### P3-1 — Reduce dual schema ownership incrementally
 
-**Status (2026-08-30): in progress.** All 49 model tables now have an executable, disjoint creation-owner classification. Eighteen formerly reconciler-created tables—including authentication support, email-provider connections, CV persistence/history, job-workspace AI notes, append-only AI interactions, and application workflow checklists—have moved through additive provider-aware migrations with legacy-row preservation, downgrade/retry safety, startup-DDL removal, fresh SQLite runtime proof and generated MariaDB SQL. The Gmail decision migration also closes its missing MariaDB creation path. Seventeen startup-created tables remain; see `docs/verification/jt-019-schema-ownership.md` and V-194–V-204.
+**Status (2026-08-30): in progress.** All 49 model tables now have an executable, disjoint creation-owner classification. Nineteen formerly reconciler-created tables—including authentication support, email-provider connections, CV persistence/history, job-workspace AI notes, append-only AI interactions, workflow checklists, and cover-letter history—have moved through additive provider-aware migrations with legacy-row preservation, downgrade/retry safety, startup-DDL removal, fresh SQLite runtime proof and generated MariaDB SQL. The Gmail decision migration also closes its missing MariaDB creation path. Sixteen startup-created tables remain; see `docs/verification/jt-019-schema-ownership.md` and V-194–V-205.
 
 - **Findings/scope:** JT-019; inventory reconciler operations and move stable schema ownership to EF migrations in small steps.
 - **Dependencies:** provider upgrade fixtures and P2-2 restore safety.

docs/audits/verification-log.md

@@ -236,3 +236,4 @@ Output was reduced to filenames and commit counts. The token artifact appears un
 | V-202 | Ownership/migration chain; populated adoption/downgrade/retry; relationship/index assertions; MariaDB script; full backend | Repository root / disposable local SQLite | Move saved CV variants and append-only revision history to migration ownership without losing user documents | PASS — focused ownership/migration 14/14; public slug, settings and two revisions survive adoption, downgrade and re-upgrade; four indexes exist; deleting the job nulls only the CV link and deleting the CV cascades through revisions; generated MariaDB SQL is provider-safe; startup creates neither table; full backend 730/730 | MariaDB SQL generated only; no provider account or production migration. Guarded malformed-empty/index/auto-increment repair remains temporarily. Nineteen reconciler-owned tables remain | JT-019 CV variant aggregate transfer complete; career-profile aggregate and remaining feature tables continue incrementally |
 | V-203 | Ownership/migration chain; populated adoption/downgrade/retry; usage/FK/index assertions; MariaDB script; full backend | Repository root / disposable local SQLite | Move append-only AI interaction history to explicit migration ownership without losing generated results or usage data | PASS — focused ownership/migration 15/15; result JSON, mode, provider and usage counters survive adoption, downgrade and re-upgrade; both indexes exist; deleting the parent application cascades through history; generated MariaDB SQL is provider-safe; startup no longer creates the table; full backend 731/731 | MariaDB SQL generated only; no provider account or production migration. Historical compatibility bootstrap and guarded counter/shape/index repairs remain. Eighteen reconciler-owned tables remain | JT-019 AI interaction transfer complete; checklist/document/preparation tables continue incrementally |
 | V-204 | Ownership/migration chain; populated adoption/downgrade/retry; workflow/FK/index assertions; MariaDB script; full backend | Repository root / disposable local SQLite | Move application workflow checklist state to migration ownership without losing automatic or manual progress | PASS — focused ownership/migration 16/16; auto-completed system and pending manual items survive adoption, downgrade and re-upgrade; idempotency/order indexes exist; deleting the parent application cascades through checklist items; generated MariaDB SQL is provider-safe; startup no longer creates the table; full backend 732/732 | MariaDB SQL generated only; no provider account or production migration. Guarded malformed-empty/index/auto-increment repair remains temporarily. Seventeen reconciler-owned tables remain | JT-019 checklist transfer complete; cover-letter and interview-preparation tables continue incrementally |
+| V-205 | Ownership/migration chain; populated adoption/downgrade/retry; document/FK/index assertions; MariaDB script; full backend | Repository root / disposable local SQLite | Move append-only cover-letter revision history to migration ownership without losing recoverable documents | PASS — focused ownership/migration 17/17; manual and AI revisions plus source/action metadata survive adoption, downgrade and re-upgrade; owner/job/version index exists; deleting the parent application cascades through history; generated MariaDB SQL is provider-safe; startup no longer creates the table; full backend 733/733 | MariaDB SQL generated only; no provider account or production migration. Guarded malformed-empty/index/auto-increment repair remains temporarily. Sixteen reconciler-owned tables remain | JT-019 cover-letter history transfer complete; interview-preparation items and career-profile aggregate continue incrementally |

docs/infrastructure/database-ownership.md

@@ -67,7 +67,7 @@ already-correct database. Two consequences worth knowing:
 Created by EF migrations, never by the reconciler:
 
 `AccountDeletionFiles`, `AccountDeletionRequests`, `AiInteractions`, `AiUsageRecords`, `AiWorkspaceNotes`,
-`ApplicationChecklistItems`, `Attachments`, `Companies`,
+`ApplicationChecklistItems`, `Attachments`, `Companies`, `CoverLetterVersions`,
 `Correspondences`, `CvExtractionRuns`, `CvUploadArtifacts`, `CvVariants`, `CvVariantVersions`,
 `EmailDrafts`, `EmailSendAttempts`, `GmailConnections`,
 `GmailReviewDecisions`, `ImapConnections`, `InterviewPrepNotes`, `JobApplications`, `JobEvents`, `Jobs`,
@@ -119,6 +119,10 @@ creates the table; only additive counter and guarded MariaDB shape/index repairs
 system-key uniqueness and owner/job/sort index preserve idempotent seeding alongside freely ordered
 manual tasks; application deletion remains cascading.
 
+`CoverLetterVersions` moved in `20260830131000_AdoptCoverLetterVersionSchema`. Manual and AI-approved
+revisions retain their source/action metadata and owner/job/version ordering; application deletion
+remains cascading.
+
 The reconciler may **repair** these (add a missing column, add an index, fix a non-`AUTO_INCREMENT`
 primary key) and may seed the default `RuleSettings` row — but it must never `CREATE TABLE` them.
 It used to create `RuleSettings`, which is precisely why a clean install failed with
@@ -130,7 +134,7 @@ Created by `StartupInitializationExtensions`, with a **no-op migration** holding
 
 `CareerProfiles`, `CareerProfileVersions`, the six CareerProfile children (`CareerExperiences`,
 `CareerEducations`, `CareerSkills`, `CareerProjects`, `CareerCertifications`, `CareerLanguages`),
-`CoverLetterVersions` and `InterviewPrepItems`.
+`InterviewPrepItems`.
 
 The seven ASP.NET Identity tables are also currently reconciler-owned, despite older wording that
 called them migration-owned: `AspNetRoles`, `AspNetUsers`, `AspNetRoleClaims`, `AspNetUserClaims`,
@@ -151,7 +155,7 @@ No-op migrations, each with a comment explaining why:
 | `20260718131138_AddAiInteractions` | historical no-op; ownership transferred by `20260830129000_AdoptAiInteractionSchema` |
 | `20260719085904_AddApplicationChecklistItems` | historical no-op; ownership transferred by `20260830130000_AdoptApplicationChecklistSchema` |
 | `20260719094728_SyncCareerChildKeyLengths` | snapshot sync only |
-| `20260719120954_AddCoverLetterVersions` | `CoverLetterVersions` |
+| `20260719120954_AddCoverLetterVersions` | historical no-op; ownership transferred by `20260830131000_AdoptCoverLetterVersionSchema` |
 | `20260719145044_AddInterviewPrepItems` | `InterviewPrepItems` |
 
 ### Dependency guards

docs/verification/jt-019-schema-ownership.md

@@ -37,6 +37,8 @@ cohesive table groups. It does not attempt to delete the legacy reconciler whole
   and historical compatibility bootstrap while retaining append-only results and usage counters.
 - Added `20260830130000_AdoptApplicationChecklistSchema` for application workflow state, retaining
   stable system keys, manual steps, completion state, and user ordering.
+- Added `20260830131000_AdoptCoverLetterVersionSchema` for append-only document history, retaining
+  manual and AI-approved text plus source/action metadata.
 - Corrected the ownership runbook: new tables now default to migrations; the reconciler is legacy
   compatibility code to retire one dependency group at a time.
 
@@ -72,14 +74,16 @@ migration.
   re-upgrade; deleting the parent application still cascades through its interaction history.
 - Representative system-generated and manual checklist steps survive adoption, downgrade, and
   re-upgrade; deleting the parent application still cascades through its workflow items.
+- Representative manual and AI cover-letter revisions survive adoption, downgrade, and re-upgrade;
+  deleting the parent application still cascades through document history.
 - Generated MariaDB SQL contains the provider-correct `SystemEmailSettings` DDL.
-- Full backend: 732/732 passed after the application checklist transfer.
+- Full backend: 733/733 passed after the cover-letter history transfer.
 - Fresh application startup over a new disposable SQLite database applied
   `20260830120000_AdoptSystemEmailSettingsSchema` and reached the healthy listening state.
 
 ## Remaining JT-019 work
 
-Seventeen model tables remain startup-created, including the Identity group and several tables
+Sixteen model tables remain startup-created, including the Identity group and several tables
 with parent dependencies. Transfer them in small dependency-aware migrations with blank, populated,
 retry and MariaDB runtime proof. Column/index repairs must remain until historical upgrade fixtures
 prove each one redundant.

docs/work-programmes/master-progress.md

@@ -54,6 +54,7 @@ Updated: 2026-08-30
 - Moved saved CV variants and append-only revision history into one provider-aware migration; public slugs, settings, indexes, job-link nulling, and history cascades are preserved.
 - Moved append-only AI interaction history into a provider-aware migration; generated results, modes, providers, usage counters, indexes, and application cascades are preserved.
 - Moved application checklist workflow state into a provider-aware migration; system-key idempotency, manual tasks, ordering, completion state, and application cascades are preserved.
+- Moved append-only cover-letter revision history into a provider-aware migration; manual and AI text, source/action metadata, ordering, and application cascades are preserved.
 
 ### In progress
 
@@ -84,7 +85,7 @@ Updated: 2026-08-30
 - Focused frontend: 2 suites, 6 tests passed.
 - Full frontend: 64 suites, 272 tests passed.
 - Next production build and TypeScript: passed.
-- Full backend: 732/732 tests passed after the application checklist JT-019 transfer.
+- Full backend: 733/733 tests passed after the cover-letter history JT-019 transfer.
 - Portable Playwright launcher: resolved the user-local .NET 9 SDK; backend Release build passed with 0 warnings/errors.
 - Playwright: initial full run 9/10 exposed the intentional mobile Settings control change; updated focused rerun passed 1/1. A final complete browser rerun remains in the end-of-batch gate.
 - Focused backend match/intelligence verification: 34/34 passed.