pigeongov 0.2.2 → 0.3.0

package/dist/src/advisory/cliff/calculator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Benefits cliff calculator.
+ *
+ * Given a household's income, size, and state, identifies every federal
+ * benefit program they currently qualify for, the exact income point
+ * where each one drops off, and the "safe raise threshold" — the
+ * income level where additional earnings more than offset the lost
+ * benefits.  Three million US households face these perverse
+ * incentives; this calculator makes them visible.
+ */
+import type { CliffAnalysis } from "../../types.js";
+export interface CliffInput {
+    annualIncome: number;
+    householdSize: number;
+    state?: string | undefined;
+}
+export declare function calculateCliff(input: CliffInput): CliffAnalysis;

package/dist/src/advisory/cliff/calculator.js

@@ -0,0 +1,117 @@
+/**
+ * Benefits cliff calculator.
+ *
+ * Given a household's income, size, and state, identifies every federal
+ * benefit program they currently qualify for, the exact income point
+ * where each one drops off, and the "safe raise threshold" — the
+ * income level where additional earnings more than offset the lost
+ * benefits.  Three million US households face these perverse
+ * incentives; this calculator makes them visible.
+ */
+import { PROGRAMS, fplPercent, getFpl } from "./programs.js";
+export function calculateCliff(input) {
+    const { annualIncome, householdSize, state = "CA" } = input;
+    // 1. Current benefits at this income
+    const currentBenefits = [];
+    for (const program of PROGRAMS) {
+        if (program.isEligible(annualIncome, householdSize)) {
+            const monthly = program.monthlyBenefit(annualIncome, householdSize);
+            if (monthly > 0) {
+                currentBenefits.push({
+                    program: program.name,
+                    monthlyValue: monthly,
+                });
+            }
+        }
+    }
+    // 2. Find cliff points — each income where a program drops off.
+    //    The loss figure is the benefit they receive *right now*, since
+    //    that's the value they'd eventually forfeit by earning past the
+    //    cutoff (even if the benefit slides down along the way).
+    const cliffPoints = [];
+    for (const program of PROGRAMS) {
+        const cutoff = program.cutoffIncome(householdSize);
+        if (cutoff > annualIncome && program.isEligible(annualIncome, householdSize)) {
+            const currentBenefit = program.monthlyBenefit(annualIncome, householdSize);
+            if (currentBenefit > 0) {
+                cliffPoints.push({
+                    income: cutoff,
+                    programLost: program.name,
+                    monthlyLoss: currentBenefit,
+                    annualLoss: currentBenefit * 12,
+                });
+            }
+        }
+    }
+    // Sort cliff points ascending by income
+    cliffPoints.sort((a, b) => a.income - b.income);
+    // 3. Calculate total current package (earnings + benefits)
+    const monthlyBenefitTotal = currentBenefits.reduce((sum, b) => sum + b.monthlyValue, 0);
+    const currentTotalAnnual = annualIncome + monthlyBenefitTotal * 12;
+    // 4. Find safe raise threshold — the income where
+    //    (new income + remaining benefits) >= current total package.
+    //    Walk income up in $500 increments for precision without being
+    //    computationally extravagant.
+    let safeRaiseThreshold = annualIncome;
+    if (cliffPoints.length > 0) {
+        const ceiling = Math.max(...cliffPoints.map((c) => c.income), annualIncome);
+        // Scan from current income to well past the last cliff
+        for (let candidate = annualIncome + 500; candidate <= ceiling + 30_000; candidate += 500) {
+            let remainingMonthly = 0;
+            for (const program of PROGRAMS) {
+                if (program.isEligible(candidate, householdSize)) {
+                    remainingMonthly += program.monthlyBenefit(candidate, householdSize);
+                }
+            }
+            const candidateTotal = candidate + remainingMonthly * 12;
+            if (candidateTotal >= currentTotalAnnual) {
+                safeRaiseThreshold = candidate;
+                break;
+            }
+        }
+        // If we never found a break-even, the furthest cliff + buffer
+        if (safeRaiseThreshold === annualIncome && cliffPoints.length > 0) {
+            safeRaiseThreshold = ceiling + 5_000;
+        }
+    }
+    // 5. Generate recommendation
+    const recommendation = buildRecommendation(annualIncome, householdSize, state, currentBenefits, cliffPoints, safeRaiseThreshold);
+    return {
+        currentIncome: annualIncome,
+        householdSize,
+        state,
+        currentBenefits,
+        cliffPoints,
+        safeRaiseThreshold,
+        recommendation,
+    };
+}
+function buildRecommendation(income, householdSize, state, benefits, cliffs, safeThreshold) {
+    const fplPct = fplPercent(income, householdSize);
+    const fpl = getFpl(householdSize);
+    if (benefits.length === 0) {
+        return (`At $${income.toLocaleString()}/year (${Math.round(fplPct)}% FPL for a household of ${householdSize}), ` +
+            `this household is above the eligibility thresholds for the major federal benefit programs. ` +
+            `No benefits cliffs apply.`);
+    }
+    const totalMonthly = benefits.reduce((s, b) => s + b.monthlyValue, 0);
+    const totalAnnual = totalMonthly * 12;
+    const programNames = benefits.map((b) => b.program).join(", ");
+    let text = `At $${income.toLocaleString()}/year (${Math.round(fplPct)}% FPL for a household of ${householdSize} in ${state}), ` +
+        `this household currently receives an estimated $${totalMonthly.toLocaleString()}/month ` +
+        `($${totalAnnual.toLocaleString()}/year) in benefits from: ${programNames}. `;
+    if (cliffs.length > 0) {
+        const nearestCliff = cliffs[0];
+        text +=
+            `The nearest cliff is at $${nearestCliff.income.toLocaleString()}/year, ` +
+                `where ${nearestCliff.programLost} drops off (losing $${nearestCliff.annualLoss.toLocaleString()}/year). `;
+    }
+    if (safeThreshold > income) {
+        const raiseNeeded = safeThreshold - income;
+        text +=
+            `To safely increase income without a net loss, aim for at least ` +
+                `$${safeThreshold.toLocaleString()}/year — a raise of $${raiseNeeded.toLocaleString()}/year.`;
+    }
+    return text;
+}
+//# sourceMappingURL=calculator.js.map

package/dist/src/advisory/cliff/calculator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculator.js","sourceRoot":"","sources":["../../../../src/advisory/cliff/calculator.ts"],"names":[],"mappings":"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"}

package/dist/src/advisory/cliff/programs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Federal poverty level constants and benefit program definitions.
+ *
+ * FPL figures are 2025 HHS guidelines for the 48 contiguous states + DC.
+ * Alaska and Hawaii use higher thresholds in practice, but we use the
+ * continental baseline here — conservative is honest.
+ */
+export declare const FPL_BASE = 15650;
+export declare const FPL_PER_ADDITIONAL = 5580;
+export declare function getFpl(householdSize: number): number;
+export declare function fplPercent(income: number, householdSize: number): number;
+export interface ProgramDefinition {
+    id: string;
+    name: string;
+    /** FPL percentage cutoff — income above this kills eligibility */
+    cutoffFplPercent: number;
+    /** Whether this household size + income qualifies */
+    isEligible: (income: number, householdSize: number) => boolean;
+    /** Monthly benefit value at given income */
+    monthlyBenefit: (income: number, householdSize: number) => number;
+    /** Income at which eligibility ends */
+    cutoffIncome: (householdSize: number) => number;
+}
+export declare const PROGRAMS: ProgramDefinition[];

package/dist/src/advisory/cliff/programs.js

@@ -0,0 +1,108 @@
+/**
+ * Federal poverty level constants and benefit program definitions.
+ *
+ * FPL figures are 2025 HHS guidelines for the 48 contiguous states + DC.
+ * Alaska and Hawaii use higher thresholds in practice, but we use the
+ * continental baseline here — conservative is honest.
+ */
+// --- FPL 2025 ---
+export const FPL_BASE = 15_650;
+export const FPL_PER_ADDITIONAL = 5_580;
+export function getFpl(householdSize) {
+    if (householdSize < 1)
+        return FPL_BASE;
+    return FPL_BASE + FPL_PER_ADDITIONAL * (householdSize - 1);
+}
+export function fplPercent(income, householdSize) {
+    return (income / getFpl(householdSize)) * 100;
+}
+// SNAP max monthly allotments by household size (FY2025)
+const SNAP_MAX_ALLOTMENTS = {
+    1: 292,
+    2: 536,
+    3: 768,
+    4: 975,
+    5: 1_158,
+    6: 1_390,
+    7: 1_536,
+    8: 1_756,
+};
+function getSnapMaxAllotment(householdSize) {
+    if (householdSize <= 0)
+        return 0;
+    if (householdSize <= 8)
+        return SNAP_MAX_ALLOTMENTS[householdSize] ?? 0;
+    // Each additional person above 8 adds ~$220
+    return (SNAP_MAX_ALLOTMENTS[8] ?? 1_756) + (householdSize - 8) * 220;
+}
+export const PROGRAMS = [
+    {
+        id: "snap",
+        name: "SNAP (Food Stamps)",
+        cutoffFplPercent: 130,
+        isEligible: (income, hs) => income <= getFpl(hs) * 1.3,
+        monthlyBenefit: (income, hs) => {
+            if (income > getFpl(hs) * 1.3)
+                return 0;
+            const max = getSnapMaxAllotment(hs);
+            // Benefit reduces by 30% of net income above a deduction floor
+            const standardDeduction = hs <= 3 ? 198 : hs <= 5 ? 208 : 239;
+            const monthlyIncome = income / 12;
+            const netIncome = Math.max(0, monthlyIncome - standardDeduction);
+            const reduction = netIncome * 0.3;
+            return Math.max(0, Math.round(max - reduction));
+        },
+        cutoffIncome: (hs) => Math.floor(getFpl(hs) * 1.3),
+    },
+    {
+        id: "medicaid",
+        name: "Medicaid",
+        cutoffFplPercent: 138,
+        isEligible: (income, hs) => income <= getFpl(hs) * 1.38,
+        monthlyBenefit: (_income, _hs) => 600,
+        cutoffIncome: (hs) => Math.floor(getFpl(hs) * 1.38),
+    },
+    {
+        id: "wic",
+        name: "WIC",
+        cutoffFplPercent: 185,
+        isEligible: (income, hs) => income <= getFpl(hs) * 1.85,
+        monthlyBenefit: (_income, _hs) => 75,
+        cutoffIncome: (hs) => Math.floor(getFpl(hs) * 1.85),
+    },
+    {
+        id: "liheap",
+        name: "LIHEAP (Energy Assistance)",
+        cutoffFplPercent: 150,
+        isEligible: (income, hs) => income <= getFpl(hs) * 1.5,
+        monthlyBenefit: (_income, _hs) => 50,
+        cutoffIncome: (hs) => Math.floor(getFpl(hs) * 1.5),
+    },
+    {
+        id: "aca_subsidy",
+        name: "ACA Premium Subsidy",
+        cutoffFplPercent: 400,
+        isEligible: (income, hs) => {
+            const pct = fplPercent(income, hs);
+            return pct >= 100 && pct <= 400;
+        },
+        monthlyBenefit: (income, hs) => {
+            const pct = fplPercent(income, hs);
+            if (pct < 100 || pct > 400)
+                return 0;
+            // Linear slide: $500/mo at 150% FPL -> $50/mo at 400% FPL
+            const t = Math.min(1, Math.max(0, (pct - 150) / (400 - 150)));
+            return Math.round(500 - t * 450);
+        },
+        cutoffIncome: (hs) => Math.floor(getFpl(hs) * 4.0),
+    },
+    {
+        id: "chip",
+        name: "CHIP (Children's Health Insurance)",
+        cutoffFplPercent: 200,
+        isEligible: (income, hs) => income <= getFpl(hs) * 2.0,
+        monthlyBenefit: (_income, _hs) => 200,
+        cutoffIncome: (hs) => Math.floor(getFpl(hs) * 2.0),
+    },
+];
+//# sourceMappingURL=programs.js.map

package/dist/src/advisory/cliff/programs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"programs.js","sourceRoot":"","sources":["../../../../src/advisory/cliff/programs.ts"],"names":[],"mappings":"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"}

package/dist/src/advisory/cost/estimator.d.ts

@@ -0,0 +1,12 @@
+import type { CostEstimate } from "../../types.js";
+/**
+ * Estimate the cost of a government workflow across three tiers:
+ * DIY, with PigeonGov (free tooling), and with an attorney.
+ *
+ * Returns `null` for unknown workflows.
+ */
+export declare function estimateCost(workflowId: string): CostEstimate | null;
+/**
+ * List all workflow IDs that have cost data available.
+ */
+export declare function listAvailableCosts(): string[];

package/dist/src/advisory/cost/estimator.js

@@ -0,0 +1,160 @@
+const COST_DATABASE = {
+    "tax/1040": {
+        fees: [
+            { item: "Federal e-file", min: 0, max: 0, type: "filing" },
+        ],
+        attorney: {
+            min: 200,
+            max: 1200,
+            description: "CPA or enrolled agent preparation fee — varies by return complexity",
+        },
+    },
+    "immigration/family-visa-intake": {
+        fees: [
+            { item: "I-130 filing fee", min: 675, max: 675, type: "filing" },
+            { item: "I-485 filing fee", min: 1440, max: 1440, type: "filing" },
+            { item: "Biometrics fee", min: 85, max: 85, type: "biometric" },
+            { item: "Medical examination (I-693)", min: 200, max: 500, type: "medical" },
+        ],
+        attorney: {
+            min: 2000,
+            max: 5000,
+            description: "Immigration attorney for family-based petition through adjustment of status",
+        },
+    },
+    "immigration/naturalization": {
+        fees: [
+            { item: "N-400 filing fee", min: 760, max: 760, type: "filing" },
+            { item: "Passport-style photos", min: 10, max: 30, type: "photo" },
+        ],
+        attorney: {
+            min: 1500,
+            max: 7500,
+            description: "Immigration attorney for naturalization — higher end for complex cases",
+        },
+    },
+    "legal/small-claims": {
+        fees: [
+            { item: "Court filing fee", min: 75, max: 75, type: "filing" },
+            { item: "Service of process", min: 20, max: 75, type: "service" },
+        ],
+        attorney: {
+            min: 500,
+            max: 2000,
+            description: "Attorney representation or consultation for small claims matter",
+        },
+    },
+    "legal/expungement": {
+        fees: [
+            { item: "Petition filing fee", min: 250, max: 250, type: "filing" },
+            { item: "Background check", min: 25, max: 50, type: "background" },
+            { item: "Fingerprinting", min: 20, max: 50, type: "biometric" },
+        ],
+        attorney: {
+            min: 900,
+            max: 3000,
+            description: "Attorney for criminal record expungement petition and hearing",
+        },
+    },
+    "estate/basic-will": {
+        fees: [
+            { item: "Notarization", min: 10, max: 25, type: "notarization" },
+        ],
+        attorney: {
+            min: 300,
+            max: 1500,
+            description: "Estate attorney for will drafting and execution",
+        },
+    },
+    "identity/passport": {
+        fees: [
+            { item: "DS-11 application fee", min: 165, max: 165, type: "filing" },
+            { item: "Execution / acceptance fee", min: 35, max: 35, type: "service" },
+            { item: "Passport photos", min: 10, max: 20, type: "photo" },
+            { item: "Expedited processing", min: 0, max: 60, type: "expedite" },
+        ],
+        attorney: {
+            min: 100,
+            max: 400,
+            description: "Passport expediting service or attorney assistance — rarely needed",
+        },
+    },
+    "identity/name-change": {
+        fees: [
+            { item: "Court petition filing fee", min: 200, max: 200, type: "filing" },
+            { item: "Legal publication requirement", min: 0, max: 150, type: "publication" },
+            { item: "Certified copies of order", min: 10, max: 50, type: "optional" },
+        ],
+        attorney: {
+            min: 300,
+            max: 1000,
+            description: "Attorney for name change petition, publication, and court appearance",
+        },
+    },
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function sumBreakdown(fees, pick) {
+    return fees.reduce((acc, f) => acc + f[pick], 0);
+}
+function toBreakdown(fees, pick) {
+    return fees.map((f) => ({ item: f.item, amount: f[pick], type: f.type }));
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Estimate the cost of a government workflow across three tiers:
+ * DIY, with PigeonGov (free tooling), and with an attorney.
+ *
+ * Returns `null` for unknown workflows.
+ */
+export function estimateCost(workflowId) {
+    const entry = COST_DATABASE[workflowId];
+    if (!entry)
+        return null;
+    const diyMin = sumBreakdown(entry.fees, "min");
+    const diyMax = sumBreakdown(entry.fees, "max");
+    // PigeonGov is free — same government fees, no tool surcharge
+    const withToolMin = diyMin;
+    const withToolMax = diyMax;
+    const attMin = diyMin + entry.attorney.min;
+    const attMax = diyMax + entry.attorney.max;
+    // Savings: compare midpoint of attorney range to midpoint of with-tool
+    const attMid = (attMin + attMax) / 2;
+    const toolMid = (withToolMin + withToolMax) / 2;
+    const vsAttorney = Math.round(attMid - toolMid);
+    return {
+        workflowId,
+        diyTotal: {
+            min: diyMin,
+            max: diyMax,
+            breakdown: toBreakdown(entry.fees, "min"),
+        },
+        withToolTotal: {
+            min: withToolMin,
+            max: withToolMax,
+            breakdown: toBreakdown(entry.fees, "min"),
+        },
+        withAttorneyTotal: {
+            min: attMin,
+            max: attMax,
+            breakdown: [
+                ...toBreakdown(entry.fees, "min"),
+                { item: "Attorney fee", amount: entry.attorney.min, type: "attorney" },
+            ],
+        },
+        savings: {
+            vsAttorney,
+            description: entry.attorney.description,
+        },
+    };
+}
+/**
+ * List all workflow IDs that have cost data available.
+ */
+export function listAvailableCosts() {
+    return Object.keys(COST_DATABASE).sort();
+}
+//# sourceMappingURL=estimator.js.map

package/dist/src/advisory/cost/estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimator.js","sourceRoot":"","sources":["../../../../src/advisory/cost/estimator.ts"],"names":[],"mappings":"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"}

package/dist/src/advisory/dependencies/data.d.ts

@@ -0,0 +1,11 @@
+import type { WorkflowDependency } from "../../types.js";
+/**
+ * Cross-agency dependency graph for PigeonGov workflows.
+ *
+ * Each edge encodes a real-world regulatory or procedural relationship
+ * between two government workflows. The graph powers downstream cascade
+ * detection ("you just naturalized — here's everything else that changes")
+ * and upstream requirement surfacing ("voter registration expects one of
+ * these preconditions to be in place").
+ */
+export declare const WORKFLOW_DEPENDENCIES: WorkflowDependency[];