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>

apps/outreach-worker/src/sources/irs-990pf/index-csv.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+
+import { selectFilings } from './index-csv.js';
+
+const HEADER =
+  'RETURN_ID,FILING_TYPE,EIN,TAX_PERIOD,SUB_DATE,TAXPAYER_NAME,RETURN_TYPE,DLN,OBJECT_ID,XML_BATCH_ID';
+
+function row(fields: {
+  returnId?: string;
+  filingType?: string;
+  ein: string;
+  taxPeriod: string;
+  subDate?: string;
+  taxpayerName?: string;
+  returnType: string;
+  dln?: string;
+  objectId: string;
+  batchId: string;
+}): string {
+  return [
+    fields.returnId ?? '1',
+    fields.filingType ?? 'EFILE',
+    fields.ein,
+    fields.taxPeriod,
+    fields.subDate ?? '20270301',
+    fields.taxpayerName ?? 'SOME FOUNDATION',
+    fields.returnType,
+    fields.dln ?? '93000000000000',
+    fields.objectId,
+    fields.batchId,
+  ].join(',');
+}
+
+describe('selectFilings', () => {
+  it('keeps only RETURN_TYPE === "990PF" rows', () => {
+    const csv = [
+      HEADER,
+      row({
+        ein: '020123456',
+        taxPeriod: '202612',
+        returnType: '990PF',
+        objectId: '111',
+        batchId: 'BATCH1',
+      }),
+      row({
+        ein: '020654321',
+        taxPeriod: '202612',
+        returnType: '990',
+        objectId: '222',
+        batchId: 'BATCH1',
+      }),
+    ].join('\n');
+
+    const targetEins = new Set(['020123456', '020654321']);
+    const filings = selectFilings(csv, targetEins);
+    expect(filings).toHaveLength(1);
+    expect(filings[0]?.ein).toBe('020123456');
+  });
+
+  it('filters to the target EIN set', () => {
+    const csv = [
+      HEADER,
+      row({
+        ein: '020999999',
+        taxPeriod: '202612',
+        returnType: '990PF',
+        objectId: '333',
+        batchId: 'BATCH1',
+      }),
+    ].join('\n');
+
+    expect(selectFilings(csv, new Set(['020123456']))).toEqual([]);
+  });
+
+  it('zero-pads a short EIN before matching against the target set', () => {
+    const csv = [
+      HEADER,
+      row({
+        ein: '20123456', // 8 digits
+        taxPeriod: '202612',
+        returnType: '990PF',
+        objectId: '444',
+        batchId: 'BATCH1',
+      }),
+    ].join('\n');
+
+    const filings = selectFilings(csv, new Set(['020123456']));
+    expect(filings).toHaveLength(1);
+    expect(filings[0]?.ein).toBe('020123456');
+  });
+
+  it('keeps only the LATEST TAX_PERIOD per EIN within the file', () => {
+    const csv = [
+      HEADER,
+      row({
+        ein: '020123456',
+        taxPeriod: '202512',
+        returnType: '990PF',
+        objectId: 'OLD',
+        batchId: 'BATCH1',
+      }),
+      row({
+        ein: '020123456',
+        taxPeriod: '202612',
+        returnType: '990PF',
+        objectId: 'NEW',
+        batchId: 'BATCH2',
+      }),
+    ].join('\n');
+
+    const filings = selectFilings(csv, new Set(['020123456']));
+    expect(filings).toHaveLength(1);
+    expect(filings[0]?.objectId).toBe('NEW');
+    expect(filings[0]?.batchId).toBe('BATCH2');
+  });
+
+  it('skips rows with a blank OBJECT_ID or XML_BATCH_ID', () => {
+    const csv = [
+      HEADER,
+      row({
+        ein: '020123456',
+        taxPeriod: '202612',
+        returnType: '990PF',
+        objectId: '',
+        batchId: 'BATCH1',
+      }),
+    ].join('\n');
+
+    expect(selectFilings(csv, new Set(['020123456']))).toEqual([]);
+  });
+
+  it('returns an empty array for a header-only file', () => {
+    expect(selectFilings(HEADER, new Set(['020123456']))).toEqual([]);
+  });
+
+  it('throws when required columns are missing from the header', () => {
+    expect(() => selectFilings('FOO,BAR\n1,2', new Set(['020123456']))).toThrow(
+      /missing required column/i,
+    );
+  });
+});