feat: failure reason, retry, audit trail, similarity signals (#110)

- Failed documents show error message from audit_events details
- POST /intakes/{id}/retry resets failed docs back to uploaded
- Audit trail entries include timestamp and resolved actor email
- Similar cases show match signal badges (same applicant, text match,
  semantic match, similar name, matching DOB/address, etc.)
- SQL fused CTE tracks which sub-queries fired per matched case

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

Author: muness

apps/web/src/pages/DevPage.tsx

@@ -1111,12 +1111,12 @@ export default function DevPage() {
                     <div className="rounded-lg border border-slate-200 bg-slate-50 p-4">
                       <p className="text-sm font-medium text-slate-900">Audit trail</p>
                       <ul className="mt-3 space-y-2 text-sm text-slate-700" aria-live="polite">
-                        {reviewDetail.auditEvents.map((eventName, eventIndex) => (
+                        {reviewDetail.auditEvents.map((ev, eventIndex) => (
                           <li
-                            key={`${eventName}-${eventIndex}`}
+                            key={`${ev.eventType}-${eventIndex}`}
                             className="rounded-md border border-slate-200 bg-white px-3 py-2"
                           >
-                            {formatAuditEvent(eventName)}
+                            {formatAuditEvent(ev.eventType)}
                           </li>
                         ))}
                       </ul>

apps/web/src/pages/ReviewerDashboard.tsx

@@ -679,9 +679,12 @@ type ReviewDetailProps = {
   finalizeError: string | null
   finalizeSuccess: boolean
   uncertainCount: number
+  retryBusy: boolean
+  retryError: string | null
   onFieldChange: (index: number, value: string) => void
   onNoteChange: (note: string) => void
   onFinalize: () => void
+  onRetry: () => void
   onSelectReview: (id: string) => void
 }
 
@@ -695,12 +698,16 @@ function ReviewDetail({
   finalizeError,
   finalizeSuccess,
   uncertainCount,
+  retryBusy,
+  retryError,
   onFieldChange,
   onNoteChange,
   onFinalize,
+  onRetry,
   onSelectReview,
 }: ReviewDetailProps) {
   const isFinalized = statusLabel(review.status) === 'Finalized'
+  const isFailed = statusLabel(review.status) === 'Failed'
 
   const reviewFieldMap = useMemo(() => {
     const map = new Map<string, ReviewField>()
@@ -891,8 +898,17 @@ function ReviewDetail({
                           {(sc.matchScore * 100).toFixed(0)}% match
                         </span>
                       </div>
+                      {sc.signals?.length > 0 ? (
+                        <div className="mt-1.5 flex flex-wrap gap-1">
+                          {sc.signals.map((sig) => (
+                            <span key={sig} className="rounded-full border border-slate-200 bg-white px-2 py-0.5 text-xs text-slate-500">
+                              {sig}
+                            </span>
+                          ))}
+                        </div>
+                      ) : null}
                       {sc.summary ? (
-                        <p className="mt-1 text-xs text-slate-600 line-clamp-2">{sc.summary}</p>
+                        <p className="mt-1 text-xs text-slate-500 line-clamp-2">{sc.summary}</p>
                       ) : null}
                     </button>
                   </li>
@@ -906,20 +922,46 @@ function ReviewDetail({
             <div className="border-t border-slate-100 p-4">
               <p className="text-xs font-semibold uppercase tracking-wide text-slate-500">Audit trail</p>
               <ul className="mt-2 space-y-1" aria-live="polite">
-                {review.auditEvents.map((ev, i) => (
+                {review.auditEvents.map((ev: AuditEventItem, i) => (
                   <li
-                    key={`${ev}-${i}`}
-                    className="rounded border border-slate-100 bg-slate-50 px-3 py-1.5 text-xs text-slate-700"
+                    key={`${ev.eventType}-${i}`}
+                    className="rounded border border-slate-100 bg-slate-50 px-3 py-2 text-xs"
                   >
-                    {formatAuditEvent(ev)}
+                    <div className="flex items-start justify-between gap-2">
+                      <span className="font-medium text-slate-700">{formatAuditEventType(ev.eventType)}</span>
+                      <span className="shrink-0 tabular-nums text-slate-400">{formatAuditTimestamp(ev.createdAt)}</span>
+                    </div>
+                    <span className="text-slate-500">{ev.actorEmail ?? 'system'}</span>
                   </li>
                 ))}
               </ul>
             </div>
           ) : null}
 
-          {/* Finalize */}
-          {!isFinalized ? (
+          {/* Failed state: show error and retry */}
+          {isFailed ? (
+            <div className="border-t border-slate-100 p-4">
+              <div className="rounded border border-rose-200 bg-rose-50 px-3 py-2">
+                <p className="text-xs font-medium text-rose-700">Extraction failed</p>
+                {review.failureReason ? (
+                  <p className="mt-1 text-xs text-rose-600">{review.failureReason}</p>
+                ) : null}
+              </div>
+              {retryError ? (
+                <p role="alert" aria-live="assertive" className="mt-2 text-xs text-rose-700">
+                  {retryError}
+                </p>
+              ) : null}
+              <button
+                type="button"
+                onClick={onRetry}
+                disabled={retryBusy}
+                className={`${btnSecondary} mt-3 w-full`}
+              >
+                {retryBusy ? 'Retrying\u2026' : 'Retry extraction'}
+              </button>
+            </div>
+          ) : !isFinalized ? (
             <div className="border-t border-slate-100 p-4">
               <label htmlFor="reviewer-note" className="block text-xs font-medium text-slate-700">
                 Reviewer note

apps/web/src/types.ts

@@ -63,6 +63,7 @@ export type SimilarCase = {
   templateId: string
   matchScore: number
   summary: string
+  signals: string[]
 }
 
 export type AuditEventItem = {

src/BuildingBlocks/Northwoods.Contracts/Models.cs

@@ -52,7 +52,8 @@ public sealed record SimilarCaseItem(
     string ApplicantName,
     string TemplateId,
     decimal MatchScore,
-    string Summary);
+    string Summary,
+    IReadOnlyList<string> Signals);
 
 public sealed record AuditEventItem(
     string EventType,

src/Services/Northwoods.Api/ApiHelpers.cs

@@ -13,7 +13,8 @@ internal sealed record SimilarCaseCandidate(
     string? ApplicantName,
     string? DateOfBirth,
     string? Address,
-    decimal MatchScore);
+    decimal MatchScore,
+    string[] MatchSources);
 
 internal sealed record CaseFieldValue(
     Guid IntakeId,

src/Services/Northwoods.Api/Endpoints/ReviewEndpoints.cs

@@ -458,17 +458,19 @@ AND t.date_of_birth IS NOT NULL
                   AND cp.date_of_birth = t.date_of_birth
             ),
             fused AS (
-                SELECT document_id, SUM(1.0 / (60.0 + rank)) AS match_score
+                SELECT document_id,
+                       SUM(1.0 / (60.0 + rank)) AS match_score,
+                       array_agg(DISTINCT source) AS match_sources
                 FROM (
-                    SELECT document_id, rank FROM fts
+                    SELECT document_id, rank, 'fts'     AS source FROM fts
                     UNION ALL
-                    SELECT document_id, rank FROM vector
+                    SELECT document_id, rank, 'vector'  AS source FROM vector
                     UNION ALL
-                    SELECT document_id, rank FROM name_fuzzy
+                    SELECT document_id, rank, 'name'    AS source FROM name_fuzzy
                     UNION ALL
-                    SELECT document_id, rank FROM address_fuzzy
+                    SELECT document_id, rank, 'address' AS source FROM address_fuzzy
                     UNION ALL
-                    SELECT document_id, rank FROM dob_exact
+                    SELECT document_id, rank, 'dob'     AS source FROM dob_exact
                 ) x
                 GROUP BY document_id
             )
@@ -478,7 +480,8 @@ GROUP BY document_id
                 cp.applicant_name AS ApplicantName,
                 cp.date_of_birth AS DateOfBirth,
                 cp.address AS Address,
-                ROUND(f.match_score::numeric, 4) AS MatchScore
+                ROUND(f.match_score::numeric, 4) AS MatchScore,
+                f.match_sources AS MatchSources
             FROM fused f
             JOIN case_profiles cp ON cp.document_id = f.document_id
             ORDER BY f.match_score DESC, cp.applicant_name NULLS LAST
@@ -526,7 +529,7 @@ FROM extracted_fields
                 }
             }
 
-            result.Add(new SimilarCaseItem(caseItem.IntakeId, caseItem.IntakeId, caseItem.ApplicantName ?? "Unknown applicant", caseItem.TemplateId, caseItem.MatchScore, summary));
+            result.Add(new SimilarCaseItem(caseItem.IntakeId, caseItem.IntakeId, caseItem.ApplicantName ?? "Unknown applicant", caseItem.TemplateId, caseItem.MatchScore, summary, signals));
         }
 
         return result;
@@ -541,35 +544,38 @@ private static (string Summary, IReadOnlyList<string> Signals) BuildCaseSummary(
         IReadOnlyDictionary<string, string> candidateFields)
     {
         var signals = new List<string>();
+        var sources = candidate.MatchSources ?? [];
 
+        // Field-level exact/fuzzy matches
         var candidateApplicant = candidate.ApplicantName;
         if (!string.IsNullOrWhiteSpace(candidateApplicant) && string.Equals(candidateApplicant, sourceApplicant, StringComparison.OrdinalIgnoreCase))
-        {
             signals.Add("same applicant");
-        }
+        else if (sources.Contains("name"))
+            signals.Add("similar name");
 
         var candidateDob = candidate.DateOfBirth;
         if (!string.IsNullOrWhiteSpace(candidateDob) && !string.IsNullOrWhiteSpace(sourceDob) && candidateDob == sourceDob)
-        {
             signals.Add("matching DOB");
-        }
 
         var candidateAddress = candidate.Address;
         if (!string.IsNullOrWhiteSpace(candidateAddress) && !string.IsNullOrWhiteSpace(sourceAddress) &&
             string.Equals(candidateAddress, sourceAddress, StringComparison.OrdinalIgnoreCase))
-        {
             signals.Add("matching address");
-        }
+        else if (sources.Contains("address"))
+            signals.Add("similar address");
 
         if (string.Equals(candidate.TemplateId, sourceTemplateId, StringComparison.OrdinalIgnoreCase))
-        {
             signals.Add("same template");
-        }
+
+        // Query-level signals not captured by field comparison
+        if (sources.Contains("fts"))
+            signals.Add("text match");
+
+        if (sources.Contains("vector"))
+            signals.Add("semantic match");
 
         if (signals.Count == 0)
-        {
             signals.Add("cross-field lexical overlap");
-        }
 
         var requestedServices = candidateFields.TryGetValue("requestedServices", out var services) && !string.IsNullOrWhiteSpace(services)
             ? services