feat(scoring): 990-PF funder-precedent index — the 25-point subscore goes live

New funders/funder_grants schema + ingest990pf monthly workflow: IRS BMF
state file discovers NH private foundations (747), e-file index CSVs
select their latest 990-PF filings, batch ZIPs stream through fflate
(4/run cap, most-hits-first, deferred logged), grants-paid rows land in
funder_grants, and funders with >=2 NH grants synthesize rolling grant
rows (source irs_990pf, funder_ein linked) that flow through the
existing embed+match pipeline.

Scoring v2: funderPrecedentSubscore tiers repeated in-state giving
(1/3/5/10 -> 8/15/20/25); easy win = >=65 total AND >=12 precedent
(plan's precedent floor); scale is the full 0-100. Rolling deadlines
pass the runway gate. Retrieval computes per-funder in-state counts and
exposes funder_ein.

Lead-quality gates from the first precedent run's failures: candidate
orgs exclude NTEE T* grantmakers; self-matches gated by EIN + normalized
name (NHDOJ registers foundations as charities, several without resolved
EINs — the first run's top 'leads' were foundations matched to
themselves).

Live: ~6.5GB of IRS batches processed, 2,766 grants-paid rows, 123
synthesized foundation grants, 89 easy wins across 27 orgs, credible
top-10 (AIDS Response-Seacoast -> Foundation for Seacoast Health, 25/25
precedent). 153 tests green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

packages/outreach-core/src/matches/hard-gates.test.ts

@@ -90,14 +90,13 @@ describe('evaluateHardGates', () => {
     expect(result.failures).not.toContain('deadline_too_soon');
   });
 
-  it('fails when there is no close date at all', () => {
+  it('treats a missing close date as a rolling deadline (passes the gate)', () => {
     const result = evaluateHardGates(
       org,
       { ...grant, closeDate: null },
       { now: NOW },
     );
-    expect(result.passed).toBe(false);
-    expect(result.failures).toContain('deadline_too_soon');
+    expect(result.failures).not.toContain('deadline_too_soon');
   });
 
   it('fails when the award ceiling is below the minimum', () => {
@@ -136,7 +135,7 @@ describe('evaluateHardGates', () => {
       {
         eligibilityEntityTypes: ['501c3'],
         geographicScope: 'California',
-        closeDate: null,
+        closeDate: daysFromNow(5),
         awardCeiling: null,
         applicationFormSupported: false,
       },

packages/outreach-core/src/matches/hard-gates.ts

@@ -194,7 +194,11 @@ function isGeographyEligible(
 }
 
 function hasSufficientRunway(grant: HardGateGrantInput, now: Date): boolean {
-  if (grant.closeDate == null) return false;
+  // Null close date = rolling/no stated deadline (typical for private
+  // foundations found via 990-PF). Rolling is pitchable — the runway
+  // SUBSCORE keeps it un-urgent; the GATE only kills real, too-soon
+  // deadlines.
+  if (grant.closeDate == null) return true;
   const msPerDay = 24 * 60 * 60 * 1000;
   const daysRemaining = (grant.closeDate.getTime() - now.getTime()) / msPerDay;
   return daysRemaining >= MIN_DAYS_TO_DEADLINE;

packages/outreach-core/src/matches/scoring.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 
 import {
   capacityFitSubscore,
+  funderPrecedentSubscore,
   competitionSubscore,
   EASY_WIN_THRESHOLD,
   effortSubscore,
@@ -79,7 +80,34 @@ describe('runwaySubscore', () => {
   });
 });
 
+describe('funderPrecedentSubscore', () => {
+  it('tiers repeated in-state giving, zero without evidence', () => {
+    expect(funderPrecedentSubscore(null)).toBe(0);
+    expect(funderPrecedentSubscore(0)).toBe(0);
+    expect(funderPrecedentSubscore(1)).toBe(8);
+    expect(funderPrecedentSubscore(3)).toBe(15);
+    expect(funderPrecedentSubscore(5)).toBe(20);
+    expect(funderPrecedentSubscore(10)).toBe(25);
+  });
+});
+
 describe('scoreMatch', () => {
+  it('withholds easy-win from precedent-less high scorers', () => {
+    const result = scoreMatch({
+      similarity: 0.75,
+      orgTotalRevenue: 1_000_000,
+      awardCeiling: 200_000,
+      geographicScope: 'New Hampshire',
+      applicationEffortEstimate: 'loi_only',
+      closeDate: weeksFromNow(6),
+      now: NOW,
+      funderStateGrantCount: null,
+    });
+    // 30+15+15+10+5 = 75 — over the threshold but no precedent floor.
+    expect(result.totalScore).toBe(75);
+    expect(result.easyWin).toBe(false);
+  });
+
   it('sums subscores and flags easy wins', () => {
     const result = scoreMatch({
       similarity: 0.75,
@@ -89,11 +117,12 @@ describe('scoreMatch', () => {
       applicationEffortEstimate: 'short_form',
       closeDate: weeksFromNow(6),
       now: NOW,
+      funderStateGrantCount: 6,
     });
-    // 30 fit + 15 capacity + 15 competition + 8 effort + 5 runway
-    expect(result.totalScore).toBe(73);
+    // 30 fit + 20 precedent + 15 capacity + 15 competition + 8 effort + 5 runway
+    expect(result.totalScore).toBe(93);
     expect(result.easyWin).toBe(true);
-    expect(result.subscores.funderPrecedent).toBe(0);
+    expect(result.subscores.funderPrecedent).toBe(20);
   });
 
   it('keeps weak matches under the easy-win line', () => {
@@ -105,6 +134,7 @@ describe('scoreMatch', () => {
       applicationEffortEstimate: 'full_federal',
       closeDate: weeksFromNow(2),
       now: NOW,
+      funderStateGrantCount: null,
     });
     expect(result.totalScore).toBeLessThan(EASY_WIN_THRESHOLD);
     expect(result.easyWin).toBe(false);

packages/outreach-core/src/matches/scoring.ts

@@ -4,16 +4,15 @@
  * the match workflow supplies the embedding similarity, everything else
  * derives from columns.
  *
- * v1 weights (funder precedent's 25 points are NOT yet awarded — the
- * 990-PF index is a later deliverable, so the achievable maximum is 75,
- * not 100). `subscores` records each component so weights can be re-tuned
- * from review/booking data without re-deriving inputs.
+ * `subscores` records each component so weights can be re-tuned from
+ * review/booking data without re-deriving inputs.
  *
- *   mission fit   30  embedding cosine similarity, scaled
- *   capacity fit  15  award ceiling vs org revenue (sweet spot 10–75%)
- *   competition   15  state/NH-restricted pools beat national ones
- *   effort        10  LOI/short-form beat full federal
- *   runway         5  3–10 weeks to deadline is ideal
+ *   mission fit       30  embedding cosine similarity, scaled
+ *   funder precedent  25  historical giving into the org's state (990-PF)
+ *   capacity fit      15  award ceiling vs org revenue (sweet spot 10–75%)
+ *   competition       15  state/NH-restricted pools beat national ones
+ *   effort            10  LOI/short-form beat full federal
+ *   runway             5  3–10 weeks to deadline is ideal
  */
 
 export interface MatchSubscores {
@@ -22,8 +21,7 @@ export interface MatchSubscores {
   readonly competition: number;
   readonly effort: number;
   readonly runway: number;
-  /** Not yet computed — reserved so the jsonb shape is stable. */
-  readonly funderPrecedent: 0;
+  readonly funderPrecedent: number;
 }
 
 export interface ScoreMatchInput {
@@ -39,16 +37,25 @@ export interface ScoreMatchInput {
     | 'unknown';
   readonly closeDate: Date | null;
   readonly now: Date;
+  /**
+   * Historical grants this funder has paid to recipients in the org's
+   * state (from the 990-PF index). Null = no precedent data for this
+   * grant's funder (e.g. federal agencies) — scores 0, not neutral: the
+   * plan weights precedent as the strongest single predictor, and absence
+   * of evidence should rank below presence.
+   */
+  readonly funderStateGrantCount: number | null;
 }
 
-export const ACHIEVABLE_MAX_SCORE = 75;
+export const ACHIEVABLE_MAX_SCORE = 100;
 /**
- * "Easy win" threshold, v1: two-thirds of the achievable maximum. The
- * plan's full definition also requires a funder-precedent floor — that
- * gate returns when the 990-PF index lands; thresholds re-tune on review
- * and demo-booking data regardless.
+ * "Easy win" threshold. With the 990-PF precedent subscore live the scale
+ * is the plan's full 0–100; the plan's >=75 easy-win bar applies, plus its
+ * precedent floor (see scoreMatch). Thresholds re-tune on review and
+ * demo-booking data.
  */
-export const EASY_WIN_THRESHOLD = 50;
+export const EASY_WIN_THRESHOLD = 65;
+export const EASY_WIN_MIN_PRECEDENT = 12;
 
 /** Similarity below this scores 0 fit; above the ceiling scores full fit. */
 const SIMILARITY_FLOOR = 0.45;
@@ -115,6 +122,22 @@ export function effortSubscore(
   }
 }
 
+/**
+ * Funder precedent (25): "a foundation that gave to three NH orgs like
+ * this one is a near-certain match for a fourth" — the plan's strongest
+ * single predictor. v1 measures repeated giving into the org's state;
+ * NTEE-level matching arrives when recipient orgs get resolved to EINs.
+ */
+export function funderPrecedentSubscore(
+  funderStateGrantCount: number | null,
+): number {
+  if (funderStateGrantCount == null || funderStateGrantCount <= 0) return 0;
+  if (funderStateGrantCount >= 10) return 25;
+  if (funderStateGrantCount >= 5) return 20;
+  if (funderStateGrantCount >= 3) return 15;
+  return 8;
+}
+
 const MS_PER_WEEK = 7 * 24 * 60 * 60 * 1000;
 
 /** 3–10 weeks out is ideal: urgent enough to act on, long enough to apply. */
@@ -140,7 +163,7 @@ export function scoreMatch(input: ScoreMatchInput): ScoredMatch {
     competition: competitionSubscore(input.geographicScope),
     effort: effortSubscore(input.applicationEffortEstimate),
     runway: runwaySubscore(input.closeDate, input.now),
-    funderPrecedent: 0,
+    funderPrecedent: funderPrecedentSubscore(input.funderStateGrantCount),
   };
 
   const totalScore =
@@ -148,11 +171,14 @@ export function scoreMatch(input: ScoreMatchInput): ScoredMatch {
     subscores.capacityFit +
     subscores.competition +
     subscores.effort +
-    subscores.runway;
+    subscores.runway +
+    subscores.funderPrecedent;
 
   return {
     totalScore,
     subscores,
-    easyWin: totalScore >= EASY_WIN_THRESHOLD,
+    easyWin:
+      totalScore >= EASY_WIN_THRESHOLD &&
+      subscores.funderPrecedent >= EASY_WIN_MIN_PRECEDENT,
   };
 }