From 7b0724136707288338c27eece740ce23fb8383e5 Mon Sep 17 00:00:00 2001
From: Lucas Winther <lucwin@ece.au.dk>
Date: Fri, 18 Sep 2026 07:28:20 +0200
Subject: [PATCH] docs: fix unnarrowable type predicate in plan Task 5 pipeline

mapWithConcurrency's callback return was inferred as a union of two object
literal types rather than one type with deep: TDeep | undefined, so the
'entry is Pair' predicate was rejected: a type predicate's type must be
assignable to its parameter's type. Added an explicit EnrichedCandidate
annotation on the call. Tests passed but tsc did not, so this was only
visible via typecheck.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/plans/2026-09-17-fuzzy-search-plan.md | 35 ++++++++++++++++------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/docs/plans/2026-09-17-fuzzy-search-plan.md b/docs/plans/2026-09-17-fuzzy-search-plan.md
index f235eb9..e3c926d 100644
--- a/docs/plans/2026-09-17-fuzzy-search-plan.md
+++ b/docs/plans/2026-09-17-fuzzy-search-plan.md
@@ -1536,18 +1536,35 @@ export async function searchPipeline<TShallow, TDeep>(
   }
 
   // Phase 2: bounded enrichment.
+  //
+  // The explicit EnrichedCandidate annotation is required, not stylistic:
+  // without it TypeScript infers the callback's return as a UNION of two
+  // object literal types ({ deep: Awaited<TDeep> } | { deep: undefined })
+  // rather than a single type with `deep: TDeep | undefined`. The narrowing
+  // predicate below is then rejected, because a type predicate's type must be
+  // assignable to its parameter's type and `Pair` is not assignable to the
+  // `{ deep: undefined }` arm.
+  interface EnrichedCandidate {
+    candidate: TShallow;
+    deep: TDeep | undefined;
+  }
+
   let enrichmentFailures = 0;
-  const enriched = await mapWithConcurrency(selected, concurrency, async (candidate) => {
-    try {
-      return { candidate, deep: await spec.enrich(candidate) };
-    } catch (error: unknown) {
-      if (isFatalSearchError(error)) {
-        throw error;
+  const enriched: EnrichedCandidate[] = await mapWithConcurrency<TShallow, EnrichedCandidate>(
+    selected,
+    concurrency,
+    async (candidate) => {
+      try {
+        return { candidate, deep: await spec.enrich(candidate) };
+      } catch (error: unknown) {
+        if (isFatalSearchError(error)) {
+          throw error;
+        }
+        enrichmentFailures++;
+        return { candidate, deep: undefined };
       }
-      enrichmentFailures++;
-      return { candidate, deep: undefined };
     }
-  });
+  );
 
   interface Pair {
     candidate: TShallow;