feat(1.8): legacy identifier linking infrastructure for extension records

Introduces the ExtensionData namespace with the full contract and service
layer that future extension records (municipality profiles, election jobs,
service configs) will use to store and validate their legacy foreign references.

- LegacyLinkType enum (JurisdictionJCode, KitId, ContactId)
- LegacyLinkReference value record with typed factory methods
- ILegacyLinkValidator / LegacyLinkValidator — validates each link type
  against the anti-corruption layer; returns descriptive errors on failure
- ILegacyLinkedRecord / ILegacyLinkedRecordProvider — contracts extension
  record types implement to participate in integrity checks
- ILegacyLinkIntegrityCheck / LegacyLinkIntegrityService — scans all
  registered providers, computes consistency percentage (NFR13 target 99.9%)
- POST /api/admin/legacy-link/integrity-check (Admin-only, audit-logged)
- 19 unit tests covering all four ACs

Stories 1.10-1.13 register ILegacyLinkedRecordProvider implementations.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Campaign_Tracker.Server.Tests/LegacyLinkIntegrityServiceTests.cs

@@ -0,0 +1,161 @@
+using Campaign_Tracker.Server.ExtensionData;
+using Campaign_Tracker.Server.LegacyData;
+using Campaign_Tracker.Server.LegacyData.Models;
+
+namespace Campaign_Tracker.Server.Tests;
+
+public sealed class LegacyLinkIntegrityServiceTests
+{
+    private static readonly DateTimeOffset FixedNow =
+        new(2026, 5, 6, 12, 0, 0, TimeSpan.Zero);
+
+    private static LegacyLinkIntegrityService BuildSut(
+        ILegacyDataAccess data,
+        params ILegacyLinkedRecordProvider[] providers)
+    {
+        var validator = new LegacyLinkValidator(data);
+        var time = new FakeTimeProvider(FixedNow);
+        return new LegacyLinkIntegrityService(providers, validator, time);
+    }
+
+    // ── AC #4 — nightly integrity check with no extension records ────────────
+
+    [Fact]
+    public async Task CheckAsync_NoProviders_ReturnsFullyConsistentReport_AC4()
+    {
+        var sut = BuildSut(new InMemoryLegacyDataAccess());
+
+        var report = await sut.CheckAsync();
+
+        Assert.True(report.IsConsistent);
+        Assert.Equal(0, report.TotalRecords);
+        Assert.Equal(0, report.FailedRecords);
+        Assert.Equal(100.0, report.ConsistencyPercentage);
+        Assert.Empty(report.Failures);
+        Assert.Equal(FixedNow, report.CheckedAt);
+    }
+
+    // ── AC #4 — consistent records produce clean report ──────────────────────
+
+    [Fact]
+    public async Task CheckAsync_AllValidLinks_Reports100PercentConsistency_AC4()
+    {
+        var data = new InMemoryLegacyDataAccess(
+            jurisdictions: [new("FAIR01", "Fairview", null, null, null, null)]);
+
+        var provider = new StubProvider(
+        [
+            new StubRecord("MunicipalityProfile", "mp-001", LegacyLinkReference.ForJurisdiction("FAIR01")),
+            new StubRecord("MunicipalityProfile", "mp-002", LegacyLinkReference.ForJurisdiction("FAIR01")),
+        ]);
+
+        var sut = BuildSut(data, provider);
+        var report = await sut.CheckAsync();
+
+        Assert.True(report.IsConsistent);
+        Assert.Equal(2, report.TotalRecords);
+        Assert.Equal(2, report.ConsistentRecords);
+        Assert.Equal(0, report.FailedRecords);
+        Assert.Equal(100.0, report.ConsistencyPercentage);
+        Assert.Empty(report.Failures);
+    }
+
+    // ── AC #4 — failing links are flagged with descriptive reason ────────────
+
+    [Fact]
+    public async Task CheckAsync_InvalidLink_FlagsRecordWithReason_AC4()
+    {
+        var data = new InMemoryLegacyDataAccess(jurisdictions: []);
+
+        var provider = new StubProvider(
+        [
+            new StubRecord("MunicipalityProfile", "mp-ghost", LegacyLinkReference.ForJurisdiction("GONE01")),
+        ]);
+
+        var sut = BuildSut(data, provider);
+        var report = await sut.CheckAsync();
+
+        Assert.False(report.IsConsistent);
+        Assert.Equal(1, report.TotalRecords);
+        Assert.Equal(0, report.ConsistentRecords);
+        Assert.Equal(1, report.FailedRecords);
+        Assert.Single(report.Failures);
+
+        var failure = report.Failures[0];
+        Assert.Equal("MunicipalityProfile", failure.RecordType);
+        Assert.Equal("mp-ghost", failure.RecordId);
+        Assert.Equal(LegacyLinkType.JurisdictionJCode, failure.Reference.Type);
+        Assert.Equal("GONE01", failure.Reference.Value);
+        Assert.Contains("GONE01", failure.Reason);
+    }
+
+    [Fact]
+    public async Task CheckAsync_MixedValidity_ReportsCorrectConsistencyPercentage_AC4()
+    {
+        var data = new InMemoryLegacyDataAccess(
+            jurisdictions: [new("GOOD01", "Good", null, null, null, null)]);
+
+        var provider = new StubProvider(
+        [
+            new StubRecord("MunicipalityProfile", "mp-good", LegacyLinkReference.ForJurisdiction("GOOD01")),
+            new StubRecord("MunicipalityProfile", "mp-bad",  LegacyLinkReference.ForJurisdiction("MISSING")),
+        ]);
+
+        var sut = BuildSut(data, provider);
+        var report = await sut.CheckAsync();
+
+        Assert.False(report.IsConsistent);
+        Assert.Equal(2, report.TotalRecords);
+        Assert.Equal(1, report.ConsistentRecords);
+        Assert.Equal(1, report.FailedRecords);
+        Assert.Equal(50.0, report.ConsistencyPercentage);
+    }
+
+    // ── AC #4 — multiple providers aggregate correctly ───────────────────────
+
+    [Fact]
+    public async Task CheckAsync_MultipleProviders_AggregatesAllRecords_AC4()
+    {
+        var data = new InMemoryLegacyDataAccess(
+            jurisdictions: [new("FAIR01", "Fairview", null, null, null, null)],
+            kits: [new LegacyKit(101, "FAIR01", null, null, null, null, false, false, null, null, null, null, null, null)]);
+
+        var providerA = new StubProvider(
+        [
+            new StubRecord("MunicipalityProfile", "mp-001", LegacyLinkReference.ForJurisdiction("FAIR01")),
+        ]);
+        var providerB = new StubProvider(
+        [
+            new StubRecord("ElectionJob", "ej-001", LegacyLinkReference.ForKit(101)),
+        ]);
+
+        var sut = BuildSut(data, providerA, providerB);
+        var report = await sut.CheckAsync();
+
+        Assert.True(report.IsConsistent);
+        Assert.Equal(2, report.TotalRecords);
+        Assert.Equal(0, report.FailedRecords);
+    }
+
+    // ── Helpers ───────────────────────────────────────────────────────────────
+
+    private sealed class StubRecord(string recordType, string recordId, LegacyLinkReference link)
+        : ILegacyLinkedRecord
+    {
+        public string RecordType => recordType;
+        public string RecordId => recordId;
+        public LegacyLinkReference LegacyLink => link;
+    }
+
+    private sealed class StubProvider(IReadOnlyList<ILegacyLinkedRecord> records)
+        : ILegacyLinkedRecordProvider
+    {
+        public Task<IReadOnlyList<ILegacyLinkedRecord>> GetAllAsync(CancellationToken cancellationToken = default)
+            => Task.FromResult(records);
+    }
+
+    private sealed class FakeTimeProvider(DateTimeOffset utcNow) : TimeProvider
+    {
+        public override DateTimeOffset GetUtcNow() => utcNow;
+    }
+}

Campaign_Tracker.Server.Tests/LegacyLinkValidatorTests.cs

@@ -0,0 +1,179 @@
+using Campaign_Tracker.Server.ExtensionData;
+using Campaign_Tracker.Server.LegacyData;
+using Campaign_Tracker.Server.LegacyData.Models;
+
+namespace Campaign_Tracker.Server.Tests;
+
+public sealed class LegacyLinkValidatorTests
+{
+    // ── AC #2 — ACL join returns correct record with no ambiguity ────────────
+
+    [Fact]
+    public async Task ValidateAsync_JurisdictionJCode_ExistingRecord_ReturnsSuccess_AC2()
+    {
+        var data = new InMemoryLegacyDataAccess(
+            jurisdictions: [new("FAIR01", "Fairview Borough", null, null, null, null)]);
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(LegacyLinkReference.ForJurisdiction("FAIR01"));
+
+        Assert.True(result.IsValid);
+        Assert.Null(result.Error);
+    }
+
+    [Fact]
+    public async Task ValidateAsync_KitId_ExistingRecord_ReturnsSuccess_AC2()
+    {
+        var kit = new LegacyKit(101, "FAIR01", null, null, null, null, false, false,
+            null, null, null, null, null, null);
+        var data = new InMemoryLegacyDataAccess(kits: [kit]);
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(LegacyLinkReference.ForKit(101));
+
+        Assert.True(result.IsValid);
+    }
+
+    [Fact]
+    public async Task ValidateAsync_ContactId_ExistingRecord_ReturnsSuccess_AC2()
+    {
+        var contact = new LegacyContact(1, "FAIR01", "Jane Doe", null, null,
+            null, null, null, null, null, null, null, null, null, null);
+        var data = new InMemoryLegacyDataAccess(contacts: [contact]);
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(LegacyLinkReference.ForContact(1));
+
+        Assert.True(result.IsValid);
+    }
+
+    [Fact]
+    public async Task ValidateAsync_JurisdictionJCode_IsCaseInsensitive_AC2()
+    {
+        var data = new InMemoryLegacyDataAccess(
+            jurisdictions: [new("FAIR01", "Fairview Borough", null, null, null, null)]);
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(LegacyLinkReference.ForJurisdiction("fair01"));
+
+        Assert.True(result.IsValid);
+    }
+
+    // ── AC #3 — invalid/non-existent reference rejected with descriptive error ─
+
+    [Fact]
+    public async Task ValidateAsync_JurisdictionJCode_NotFound_ReturnsFailureWithDescription_AC3()
+    {
+        var data = new InMemoryLegacyDataAccess(jurisdictions: []);
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(LegacyLinkReference.ForJurisdiction("UNKNOWN"));
+
+        Assert.False(result.IsValid);
+        Assert.NotNull(result.Error);
+        Assert.Contains("UNKNOWN", result.Error);
+        Assert.Contains("jurisdiction", result.Error, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ValidateAsync_KitId_NotFound_ReturnsFailureWithDescription_AC3()
+    {
+        var data = new InMemoryLegacyDataAccess(kits: []);
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(LegacyLinkReference.ForKit(9999));
+
+        Assert.False(result.IsValid);
+        Assert.NotNull(result.Error);
+        Assert.Contains("9999", result.Error);
+        Assert.Contains("kit", result.Error, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ValidateAsync_ContactId_NotFound_ReturnsFailureWithDescription_AC3()
+    {
+        var data = new InMemoryLegacyDataAccess(contacts: []);
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(LegacyLinkReference.ForContact(9999));
+
+        Assert.False(result.IsValid);
+        Assert.NotNull(result.Error);
+        Assert.Contains("9999", result.Error);
+        Assert.Contains("contact", result.Error, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ValidateAsync_BlankJCode_ReturnsFailureWithDescription_AC3()
+    {
+        var data = new InMemoryLegacyDataAccess();
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(new LegacyLinkReference(LegacyLinkType.JurisdictionJCode, "   "));
+
+        Assert.False(result.IsValid);
+        Assert.NotNull(result.Error);
+        Assert.Contains("required", result.Error, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ValidateAsync_KitId_NonIntegerValue_ReturnsFailureWithDescription_AC3()
+    {
+        var data = new InMemoryLegacyDataAccess();
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(new LegacyLinkReference(LegacyLinkType.KitId, "not-a-number"));
+
+        Assert.False(result.IsValid);
+        Assert.NotNull(result.Error);
+        Assert.Contains("not-a-number", result.Error);
+    }
+
+    [Fact]
+    public async Task ValidateAsync_ContactId_NonIntegerValue_ReturnsFailureWithDescription_AC3()
+    {
+        var data = new InMemoryLegacyDataAccess();
+        var sut = new LegacyLinkValidator(data);
+
+        var result = await sut.ValidateAsync(new LegacyLinkReference(LegacyLinkType.ContactId, "abc"));
+
+        Assert.False(result.IsValid);
+        Assert.NotNull(result.Error);
+    }
+
+    // ── AC #1 — factory methods produce correct link type and value ───────────
+
+    [Fact]
+    public void ForJurisdiction_SetsCorrectTypeAndValue_AC1()
+    {
+        var ref_ = LegacyLinkReference.ForJurisdiction("LAKE02");
+
+        Assert.Equal(LegacyLinkType.JurisdictionJCode, ref_.Type);
+        Assert.Equal("LAKE02", ref_.Value);
+    }
+
+    [Fact]
+    public void ForKit_SetsCorrectTypeAndValue_AC1()
+    {
+        var ref_ = LegacyLinkReference.ForKit(101);
+
+        Assert.Equal(LegacyLinkType.KitId, ref_.Type);
+        Assert.Equal("101", ref_.Value);
+    }
+
+    [Fact]
+    public void ForContact_SetsCorrectTypeAndValue_AC1()
+    {
+        var ref_ = LegacyLinkReference.ForContact(42);
+
+        Assert.Equal(LegacyLinkType.ContactId, ref_.Type);
+        Assert.Equal("42", ref_.Value);
+    }
+
+    [Fact]
+    public void ForJurisdiction_BlankJCode_Throws_AC1()
+    {
+        Assert.Throws<ArgumentException>(() => LegacyLinkReference.ForJurisdiction(""));
+        Assert.Throws<ArgumentException>(() => LegacyLinkReference.ForJurisdiction("   "));
+    }
+}

Campaign_Tracker.Server/Controllers/LegacyLinkController.cs

@@ -0,0 +1,89 @@
+using System.Security.Claims;
+using Campaign_Tracker.Server.Audit;
+using Campaign_Tracker.Server.Authorization;
+using Campaign_Tracker.Server.ExtensionData;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Campaign_Tracker.Server.Controllers;
+
+/// <summary>
+/// Admin API for the extension-to-legacy referential integrity check (Story 1.8 AC #4).
+/// </summary>
+[ApiController]
+[Authorize(Policy = ApplicationPolicy.AdminAccess)]
+[Route("api/admin/legacy-link")]
+public sealed class LegacyLinkController : ControllerBase
+{
+    private readonly ILegacyLinkIntegrityCheck _integrityCheck;
+    private readonly IAuditService _audit;
+    private readonly TimeProvider _timeProvider;
+
+    public LegacyLinkController(
+        ILegacyLinkIntegrityCheck integrityCheck,
+        IAuditService audit,
+        TimeProvider timeProvider)
+    {
+        _integrityCheck = integrityCheck;
+        _audit = audit;
+        _timeProvider = timeProvider;
+    }
+
+    /// <summary>
+    /// Runs the extension-to-legacy link integrity check on demand and returns a report.
+    /// Intended to be called by a scheduler for nightly runs and by admins for manual runs.
+    /// </summary>
+    [HttpPost("integrity-check")]
+    public async Task<ActionResult<LegacyLinkIntegrityResponse>> RunIntegrityCheck(
+        CancellationToken cancellationToken)
+    {
+        var report = await _integrityCheck.CheckAsync(cancellationToken);
+
+        var actor = User.Identity?.Name
+            ?? User.FindFirstValue(ClaimTypes.NameIdentifier)
+            ?? "unknown";
+
+        _audit.Record(new AuditEvent(
+            EventType: report.IsConsistent
+                ? "LEGACY_LINK_INTEGRITY_PASSED"
+                : "LEGACY_LINK_INTEGRITY_FAILED",
+            ActorIdentity: actor,
+            Resource: "legacy-link/integrity-check",
+            Outcome: $"{report.ConsistentRecords}/{report.TotalRecords} consistent ({report.ConsistencyPercentage:F2}%)",
+            TraceIdentifier: HttpContext.TraceIdentifier,
+            RecordedAt: _timeProvider.GetUtcNow()));
+
+        return Ok(LegacyLinkIntegrityResponse.From(report));
+    }
+}
+
+public sealed record LegacyLinkIntegrityResponse(
+    bool IsConsistent,
+    DateTimeOffset CheckedAt,
+    int TotalRecords,
+    int ConsistentRecords,
+    int FailedRecords,
+    double ConsistencyPercentage,
+    IReadOnlyList<LegacyLinkFailureResponse> Failures)
+{
+    public static LegacyLinkIntegrityResponse From(LegacyLinkIntegrityReport report) =>
+        new(report.IsConsistent,
+            report.CheckedAt,
+            report.TotalRecords,
+            report.ConsistentRecords,
+            report.FailedRecords,
+            report.ConsistencyPercentage,
+            report.Failures
+                .Select(f => new LegacyLinkFailureResponse(
+                    f.RecordType, f.RecordId,
+                    f.Reference.Type.ToString(), f.Reference.Value,
+                    f.Reason))
+                .ToArray());
+}
+
+public sealed record LegacyLinkFailureResponse(
+    string RecordType,
+    string RecordId,
+    string LinkType,
+    string LinkValue,
+    string Reason);

Campaign_Tracker.Server/ExtensionData/ILegacyLinkIntegrityCheck.cs

@@ -0,0 +1,10 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Runs the extension-to-legacy referential integrity check across all registered
+/// extension record types (AC #4, NFR13).
+/// </summary>
+public interface ILegacyLinkIntegrityCheck
+{
+    Task<LegacyLinkIntegrityReport> CheckAsync(CancellationToken cancellationToken = default);
+}

Campaign_Tracker.Server/ExtensionData/ILegacyLinkValidator.cs

@@ -0,0 +1,12 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Validates that a <see cref="LegacyLinkReference"/> resolves to an existing legacy record
+/// before an extension record is persisted (AC #3).
+/// </summary>
+public interface ILegacyLinkValidator
+{
+    Task<LegacyLinkValidationResult> ValidateAsync(
+        LegacyLinkReference reference,
+        CancellationToken cancellationToken = default);
+}

Campaign_Tracker.Server/ExtensionData/ILegacyLinkedRecord.cs

@@ -0,0 +1,17 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Contract that every extension record type must satisfy to participate in
+/// legacy-identifier linking (AC #1) and nightly integrity checks (AC #4).
+/// </summary>
+public interface ILegacyLinkedRecord
+{
+    /// <summary>Domain type name used in integrity reports (e.g. "MunicipalityProfile").</summary>
+    string RecordType { get; }
+
+    /// <summary>Stable identifier for this specific record instance (e.g. its primary key).</summary>
+    string RecordId { get; }
+
+    /// <summary>The required legacy foreign reference stored on this record.</summary>
+    LegacyLinkReference LegacyLink { get; }
+}

Campaign_Tracker.Server/ExtensionData/ILegacyLinkedRecordProvider.cs

@@ -0,0 +1,11 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Supplies all persisted records of one extension record type to the integrity check.
+/// Each extension record type (municipality profile, election job, etc.) registers its own
+/// implementation so the <see cref="ILegacyLinkIntegrityCheck"/> can scan across all types.
+/// </summary>
+public interface ILegacyLinkedRecordProvider
+{
+    Task<IReadOnlyList<ILegacyLinkedRecord>> GetAllAsync(CancellationToken cancellationToken = default);
+}

Campaign_Tracker.Server/ExtensionData/LegacyLinkIntegrityReport.cs

@@ -0,0 +1,24 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Result of a nightly (or on-demand) extension-to-legacy referential integrity check (AC #4).
+/// Targeting at least 99.9% <see cref="ConsistencyPercentage"/> (NFR13).
+/// </summary>
+public sealed record LegacyLinkIntegrityReport(
+    DateTimeOffset CheckedAt,
+    int TotalRecords,
+    int ConsistentRecords,
+    int FailedRecords,
+    double ConsistencyPercentage,
+    IReadOnlyList<LegacyLinkIntegrityFailure> Failures)
+{
+    /// <summary>True when no failures were detected (or no records exist to check).</summary>
+    public bool IsConsistent => FailedRecords == 0;
+}
+
+/// <summary>Describes one extension record that failed to resolve its legacy link.</summary>
+public sealed record LegacyLinkIntegrityFailure(
+    string RecordType,
+    string RecordId,
+    LegacyLinkReference Reference,
+    string Reason);

Campaign_Tracker.Server/ExtensionData/LegacyLinkIntegrityService.cs

@@ -0,0 +1,60 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Implements <see cref="ILegacyLinkIntegrityCheck"/> by scanning every record supplied
+/// by the registered <see cref="ILegacyLinkedRecordProvider"/> implementations and
+/// validating each one's legacy link through <see cref="ILegacyLinkValidator"/> (AC #4).
+/// When no providers are registered (i.e. no extension records exist yet), the report
+/// reflects zero records and 100% consistency.
+/// </summary>
+public sealed class LegacyLinkIntegrityService : ILegacyLinkIntegrityCheck
+{
+    private readonly IEnumerable<ILegacyLinkedRecordProvider> _providers;
+    private readonly ILegacyLinkValidator _validator;
+    private readonly TimeProvider _timeProvider;
+
+    public LegacyLinkIntegrityService(
+        IEnumerable<ILegacyLinkedRecordProvider> providers,
+        ILegacyLinkValidator validator,
+        TimeProvider timeProvider)
+    {
+        _providers = providers;
+        _validator = validator;
+        _timeProvider = timeProvider;
+    }
+
+    public async Task<LegacyLinkIntegrityReport> CheckAsync(CancellationToken cancellationToken = default)
+    {
+        var failures = new List<LegacyLinkIntegrityFailure>();
+        int total = 0;
+
+        foreach (var provider in _providers)
+        {
+            var records = await provider.GetAllAsync(cancellationToken);
+            foreach (var record in records)
+            {
+                total++;
+                var result = await _validator.ValidateAsync(record.LegacyLink, cancellationToken);
+                if (!result.IsValid)
+                {
+                    failures.Add(new LegacyLinkIntegrityFailure(
+                        record.RecordType,
+                        record.RecordId,
+                        record.LegacyLink,
+                        result.Error ?? "Unknown validation error"));
+                }
+            }
+        }
+
+        int consistent = total - failures.Count;
+        double pct = total == 0 ? 100.0 : (consistent / (double)total) * 100.0;
+
+        return new LegacyLinkIntegrityReport(
+            CheckedAt: _timeProvider.GetUtcNow(),
+            TotalRecords: total,
+            ConsistentRecords: consistent,
+            FailedRecords: failures.Count,
+            ConsistencyPercentage: Math.Round(pct, 4),
+            Failures: failures);
+    }
+}

Campaign_Tracker.Server/ExtensionData/LegacyLinkReference.cs

@@ -0,0 +1,23 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Immutable value object that an extension record stores as its required legacy foreign reference.
+/// Carry the <see cref="LegacyLinkType"/> and the string representation of the join key so
+/// the anti-corruption layer can resolve it unambiguously (AC #2).
+/// </summary>
+public sealed record LegacyLinkReference(LegacyLinkType Type, string Value)
+{
+    public static LegacyLinkReference ForJurisdiction(string jCode)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(jCode);
+        return new(LegacyLinkType.JurisdictionJCode, jCode);
+    }
+
+    public static LegacyLinkReference ForKit(int id) =>
+        new(LegacyLinkType.KitId, id.ToString(System.Globalization.CultureInfo.InvariantCulture));
+
+    public static LegacyLinkReference ForContact(int id) =>
+        new(LegacyLinkType.ContactId, id.ToString(System.Globalization.CultureInfo.InvariantCulture));
+
+    public override string ToString() => $"{Type}:{Value}";
+}

Campaign_Tracker.Server/ExtensionData/LegacyLinkType.cs

@@ -0,0 +1,16 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Identifies which legacy join key an extension record's link resolves through.
+/// </summary>
+public enum LegacyLinkType
+{
+    /// <summary>JCode / JurisCode — links to the legacy Jurisdiction table.</summary>
+    JurisdictionJCode,
+
+    /// <summary>ID — links to the legacy Kit table (integer primary key).</summary>
+    KitId,
+
+    /// <summary>ID — links to the legacy Contacts table (integer primary key).</summary>
+    ContactId,
+}

Campaign_Tracker.Server/ExtensionData/LegacyLinkValidationResult.cs

@@ -0,0 +1,16 @@
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Outcome of a pre-save legacy link validation (AC #3).
+/// On failure, <see cref="Error"/> contains a descriptive message identifying the invalid reference.
+/// </summary>
+public sealed record LegacyLinkValidationResult(bool IsValid, string? Error = null)
+{
+    public static LegacyLinkValidationResult Success() => new(true);
+
+    public static LegacyLinkValidationResult Failure(string error)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(error);
+        return new(false, error);
+    }
+}

Campaign_Tracker.Server/ExtensionData/LegacyLinkValidator.cs

@@ -0,0 +1,74 @@
+using Campaign_Tracker.Server.LegacyData;
+
+namespace Campaign_Tracker.Server.ExtensionData;
+
+/// <summary>
+/// Validates a <see cref="LegacyLinkReference"/> by resolving it through the
+/// anti-corruption layer (<see cref="ILegacyDataAccess"/>).
+/// Each link type maps to a unique primary-key lookup, guaranteeing no ambiguity (AC #2, AC #3).
+/// </summary>
+public sealed class LegacyLinkValidator : ILegacyLinkValidator
+{
+    private readonly ILegacyDataAccess _legacyData;
+
+    public LegacyLinkValidator(ILegacyDataAccess legacyData)
+    {
+        _legacyData = legacyData;
+    }
+
+    public async Task<LegacyLinkValidationResult> ValidateAsync(
+        LegacyLinkReference reference,
+        CancellationToken cancellationToken = default)
+    {
+        return reference.Type switch
+        {
+            LegacyLinkType.JurisdictionJCode => await ValidateJurisdictionAsync(reference.Value, cancellationToken),
+            LegacyLinkType.KitId             => await ValidateKitAsync(reference.Value, cancellationToken),
+            LegacyLinkType.ContactId         => await ValidateContactAsync(reference.Value, cancellationToken),
+            _ => LegacyLinkValidationResult.Failure($"Unknown legacy link type '{reference.Type}'."),
+        };
+    }
+
+    private async Task<LegacyLinkValidationResult> ValidateJurisdictionAsync(
+        string jCode, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(jCode))
+            return LegacyLinkValidationResult.Failure("JCode is required and cannot be blank.");
+
+        var record = await _legacyData.GetJurisdictionAsync(jCode, cancellationToken);
+        return record is null
+            ? LegacyLinkValidationResult.Failure(
+                $"No legacy jurisdiction found for JCode '{jCode}'. Verify the identifier and try again.")
+            : LegacyLinkValidationResult.Success();
+    }
+
+    private async Task<LegacyLinkValidationResult> ValidateKitAsync(
+        string rawId, CancellationToken cancellationToken)
+    {
+        if (!int.TryParse(rawId, System.Globalization.NumberStyles.Integer,
+                System.Globalization.CultureInfo.InvariantCulture, out var id))
+            return LegacyLinkValidationResult.Failure(
+                $"Kit identifier '{rawId}' is not a valid integer ID.");
+
+        var record = await _legacyData.GetKitByIdAsync(id, cancellationToken);
+        return record is null
+            ? LegacyLinkValidationResult.Failure(
+                $"No legacy kit found for ID {id}. Verify the identifier and try again.")
+            : LegacyLinkValidationResult.Success();
+    }
+
+    private async Task<LegacyLinkValidationResult> ValidateContactAsync(
+        string rawId, CancellationToken cancellationToken)
+    {
+        if (!int.TryParse(rawId, System.Globalization.NumberStyles.Integer,
+                System.Globalization.CultureInfo.InvariantCulture, out var id))
+            return LegacyLinkValidationResult.Failure(
+                $"Contact identifier '{rawId}' is not a valid integer ID.");
+
+        var record = await _legacyData.GetContactByIdAsync(id, cancellationToken);
+        return record is null
+            ? LegacyLinkValidationResult.Failure(
+                $"No legacy contact found for ID {id}. Verify the identifier and try again.")
+            : LegacyLinkValidationResult.Success();
+    }
+}

Campaign_Tracker.Server/Program.cs

@@ -4,6 +4,7 @@ using Campaign_Tracker.Server.Audit;
 using Campaign_Tracker.Server.Authentication;
 using Campaign_Tracker.Server.Authorization;
 using Campaign_Tracker.Server.Configuration;
+using Campaign_Tracker.Server.ExtensionData;
 using Campaign_Tracker.Server.LegacyData;
 using Campaign_Tracker.Server.LegacyData.Schema;
 using Microsoft.AspNetCore.Authentication.JwtBearer;
@@ -86,6 +87,13 @@ builder.Services.AddSingleton<ILegacySchemaCheckHistory, InMemoryLegacySchemaChe
 builder.Services.AddHttpClient<IKeycloakTokenClient, KeycloakTokenClient>();
 builder.Services.AddSingleton<IAuthorizationMiddlewareResultHandler, AuthorizationAuditResultHandler>();
 
+// Legacy identifier linking for extension records (Story 1.8).
+// ILegacyLinkValidator resolves references through the anti-corruption layer (AC #2, AC #3).
+// ILegacyLinkIntegrityCheck scans all registered extension record providers (AC #4, NFR13).
+// Additional ILegacyLinkedRecordProvider registrations are added by each extension record story.
+builder.Services.AddScoped<ILegacyLinkValidator, LegacyLinkValidator>();
+builder.Services.AddScoped<ILegacyLinkIntegrityCheck, LegacyLinkIntegrityService>();
+
 var allowedOrigins = builder.Configuration.GetSection("AllowedOrigins").Get<string[]>() ?? [];
 builder.Services.AddCors(options =>
 {

_bmad-output/implementation-artifacts/1-8-legacy-identifier-linking-for-extension-records.md

@@ -1,6 +1,6 @@
 # Story 1.8: Legacy Identifier Linking for Extension Records
 
-Status: ready-for-dev
+Status: review
 
 ## Story
 
@@ -17,18 +17,18 @@ so that all new capabilities join deterministically to legacy Access records in
 
 ## Tasks / Subtasks
 
-- [ ] Implement story behavior in aligned backend/frontend modules (AC: #1)
-  - [ ] Add or update API/service/UI components required by the story scope
-  - [ ] Keep legacy Access entities read-only and route writes to extension-layer structures
-- [ ] Cover acceptance criteria #2 in implementation and tests (AC: #2)
-  - [ ] Add validation/error handling and UX state updates as needed
-- [ ] Cover acceptance criteria #3 in implementation and tests (AC: #3)
-  - [ ] Add validation/error handling and UX state updates as needed
-- [ ] Cover acceptance criteria #4 in implementation and tests (AC: #4)
-  - [ ] Add validation/error handling and UX state updates as needed
-- [ ] Validate and document completion evidence
-  - [ ] Verify build/tests for touched modules
-  - [ ] Capture changed files and any migration/config implications
+- [x] Implement story behavior in aligned backend/frontend modules (AC: #1)
+  - [x] Add or update API/service/UI components required by the story scope
+  - [x] Keep legacy Access entities read-only and route writes to extension-layer structures
+- [x] Cover acceptance criteria #2 in implementation and tests (AC: #2)
+  - [x] Add validation/error handling and UX state updates as needed
+- [x] Cover acceptance criteria #3 in implementation and tests (AC: #3)
+  - [x] Add validation/error handling and UX state updates as needed
+- [x] Cover acceptance criteria #4 in implementation and tests (AC: #4)
+  - [x] Add validation/error handling and UX state updates as needed
+- [x] Validate and document completion evidence
+  - [x] Verify build/tests for touched modules
+  - [x] Capture changed files and any migration/config implications
 
 ## Dev Notes
 
@@ -52,18 +52,46 @@ so that all new capabilities join deterministically to legacy Access records in
 
 ### Agent Model Used
 
-GPT-5 Codex
+claude-sonnet-4-6
 
 ### Debug Log References
 
-- Story generated from epic source and architecture/UX planning artifacts.
+- All 19 new unit tests pass; all 87 existing server tests pass; all 28 frontend tests pass.
 
 ### Completion Notes List
 
-- Story context created and marked ready-for-dev.
+- Introduced `Campaign_Tracker.Server/ExtensionData/` namespace with the full linking infrastructure.
+- `LegacyLinkType` enum defines the three join-key domains: JurisdictionJCode, KitId, ContactId.
+- `LegacyLinkReference` immutable record stores the type+value pair; factory methods enforce non-blank JCode.
+- `LegacyLinkValidationResult` captures success/failure with a descriptive error string.
+- `ILegacyLinkValidator` / `LegacyLinkValidator`: resolves each link type through the anti-corruption layer (`ILegacyDataAccess`), guaranteeing unambiguous resolution per AC #2; rejects unknown/missing identifiers per AC #3.
+- `ILegacyLinkedRecord` / `ILegacyLinkedRecordProvider`: contracts that every future extension record type implements to participate in AC #1 and AC #4.
+- `LegacyLinkIntegrityReport` + `LegacyLinkIntegrityFailure`: report model for AC #4.
+- `ILegacyLinkIntegrityCheck` / `LegacyLinkIntegrityService`: scans all registered providers, validates each record's link, computes consistency percentage. Empty provider set → 100% consistent (no records to fail).
+- `LegacyLinkController` (POST `/api/admin/legacy-link/integrity-check`, Admin-only): on-demand integrity check with audit event.
+- `Program.cs`: registered `ILegacyLinkValidator` and `ILegacyLinkIntegrityCheck` as scoped services.
+- 19 unit tests cover all four ACs across validator and integrity service.
+- Stories 1.10–1.13 will register their own `ILegacyLinkedRecordProvider` implementations to feed the nightly check.
 
 ### File List
 
-- `_bmad-output/implementation-artifacts/1-8-legacy-identifier-linking-for-extension-records.md`
-
-
+- `Campaign_Tracker.Server/ExtensionData/LegacyLinkType.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/LegacyLinkReference.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/LegacyLinkValidationResult.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/ILegacyLinkValidator.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/LegacyLinkValidator.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/ILegacyLinkedRecord.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/ILegacyLinkedRecordProvider.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/LegacyLinkIntegrityReport.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/ILegacyLinkIntegrityCheck.cs` (new)
+- `Campaign_Tracker.Server/ExtensionData/LegacyLinkIntegrityService.cs` (new)
+- `Campaign_Tracker.Server/Controllers/LegacyLinkController.cs` (new)
+- `Campaign_Tracker.Server/Program.cs` (modified — added ExtensionData using + service registrations)
+- `Campaign_Tracker.Server.Tests/LegacyLinkValidatorTests.cs` (new — 12 tests)
+- `Campaign_Tracker.Server.Tests/LegacyLinkIntegrityServiceTests.cs` (new — 7 tests)
+- `_bmad-output/implementation-artifacts/1-8-legacy-identifier-linking-for-extension-records.md` (this file)
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (modified — status updated)
+
+## Change Log
+
+- 2026-05-06: Story 1.8 implemented — legacy identifier linking infrastructure introduced in new `ExtensionData` namespace. Validator, integrity check service, admin API endpoint, and 19 unit tests added. All 4 ACs satisfied. (claude-sonnet-4-6)

_bmad-output/implementation-artifacts/sprint-status.yaml

@@ -35,7 +35,7 @@
 # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
 
 generated: '2026-05-05T12:00:44-04:00'
-last_updated: '2026-05-06T14:05:00-04:00'
+last_updated: '2026-05-06T15:00:00-04:00'
 project: 'Campaign_Tracker App'
 project_key: 'NOKEY'
 tracking_system: 'file-system'
@@ -50,7 +50,7 @@ development_status:
   1-5-shared-audit-logging-infrastructure: done
   1-6-legacy-anti-corruption-data-access-layer: done
   1-7-legacy-schema-compatibility-validation-gate: review
-  1-8-legacy-identifier-linking-for-extension-records: ready-for-dev
+  1-8-legacy-identifier-linking-for-extension-records: review
   1-9-seed-system-reference-values-rule-defaults: ready-for-dev
   1-10-municipality-account-profile: ready-for-dev
   1-11-municipality-operational-addresses: ready-for-dev