@paro.io/expert-shared-components 1.14.70 → 1.14.72

package/lib/tax-axis/lib/adapters/useEngineOutput.js

@@ -1,56 +1,156 @@
 "use strict";
+// useEngineOutput — maps raw engine output + formula pre-computed results
+// into the canonical Strategy[] + ComputedMap consumed by report components.
+//
+// Only strategies validated by the deterministic formula engine are included.
+// This prevents LLM-hallucinated strategies and dollar amounts from reaching
+// the Client Report or Preparer Workpaper.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useEngineOutput = useEngineOutput;
 const react_1 = require("react");
-function humanize(id) {
-    return id
-        .replace(/[_-]/g, " ")
-        .replace(/\b\w/g, (c) => c.toUpperCase());
+const strategyNarrative_1 = require("../data/strategyNarrative");
+const data_1 = require("../data");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Parse "S10" -> 10. Returns null if strategyId doesn't match the SN pattern. */
+function parseStrategyNumber(strategyId) {
+    const match = strategyId.match(/^S(\d+)$/);
+    return match ? parseInt(match[1], 10) : null;
 }
-function mapSingleStrategy(sa, idx) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
-    const ct = (_a = sa.calculation_trace) !== null && _a !== void 0 ? _a : {};
-    const lo = (_d = (_b = sa.lo) !== null && _b !== void 0 ? _b : (_c = sa.estimatedSavings) === null || _c === void 0 ? void 0 : _c.min) !== null && _d !== void 0 ? _d : 0;
-    const hi = (_g = (_e = sa.hi) !== null && _e !== void 0 ? _e : (_f = sa.estimatedSavings) === null || _f === void 0 ? void 0 : _f.max) !== null && _g !== void 0 ? _g : 0;
-    const weightedScore = (_j = (_h = sa.weighted_score) !== null && _h !== void 0 ? _h : sa.score) !== null && _j !== void 0 ? _j : (sa.priority === "HIGH" ? 85 : sa.priority === "MEDIUM" ? 70 : 55);
-    const timelineBucket = (_k = sa.timeline_bucket) !== null && _k !== void 0 ? _k : (sa.priority === "HIGH" ? "now" : "90d");
+// Static catalog lookups keyed by original strategy rank (1-25).
+const CATEGORY_BY_RANK = new Map();
+const CODE_BY_RANK = new Map();
+for (const s of data_1.STRATEGIES) {
+    CATEGORY_BY_RANK.set(s.rank, s.cat);
+    CODE_BY_RANK.set(s.rank, s.code);
+}
+// Deterministic timeline bucket assignment by strategy number.
+// Overrides LLM-assigned buckets to ensure consistent reports across runs.
+// Bucket assignment logic:
+//   now:  CPA can action in <2 hours, no external coordination needed
+//   30d:  Requires professional setup, plan changes, or payroll adjustments
+//   90d:  Requires specialist studies, amended returns, or multi-party coordination
+const TIMELINE_BUCKET_BY_STRATEGY = {
+    // --- THIS WEEK: Documentation, reclassification, simple calculations ---
+    10: "now", // S10 Business Meals §274 — reclassify existing expenses
+    11: "now", // S11 Home Office §280A — calculate deduction, measure space
+    13: "now", // S13 Augusta Rule §280A(g) — document rental days
+    17: "now", // S17 Vehicle Expense §274 — review mileage logs, elect method
+    // --- WITHIN 30 DAYS: Professional action, plan setup, payroll changes ---
+    1: "30d", // S1  S-Corp Salary §3121 — BLS benchmarking memo, payroll adjustment
+    2: "30d", // S2  Section 179 — asset purchase timing, election
+    3: "30d", // S3  Bonus Depreciation §168(k) — election decision
+    7: "30d", // S7  Retirement §401(k) — plan design review, contribution change
+    9: "30d", // S9  HSA §223 — enrollment, contribution adjustment
+    12: "30d", // S12 Accountable Plan §62 — establish/update plan document
+    14: "30d", // S14 Family Employment §73 — payroll onboarding, age verification
+    21: "30d", // S21 Tips Deduction (OBBBA) — payroll system update
+    22: "30d", // S22 Overtime Deduction (OBBBA) — payroll system update
+    25: "30d", // S25 Trump Accounts (OBBBA) — account establishment
+    // --- WITHIN 90 DAYS: Specialist study, amended returns, multi-party coordination ---
+    4: "90d", // S4  QBI §199A — SSTB analysis, entity structure review
+    5: "90d", // S5  R&D Credit §41 — specialist study, Form 6765 prep
+    6: "90d", // S6  WOTC §51 — certification process, hiring program setup
+    8: "90d", // S8  Cost Segregation §168 — engineering study required
+    15: "90d", // S15 PTE/SALT — state election filing, deadline coordination
+    16: "90d", // S16 §179D Energy — energy efficiency certification required
+    18: "90d", // S18 Insurance §79/§264 — carrier coordination, policy restructuring
+    19: "90d", // S19 §1031 Like-Kind — qualified intermediary, identification periods
+    20: "90d", // S20 QSBS §1202 — stock qualification analysis, holding period review
+    23: "90d", // S23 §174A R&E Catch-Up — amended returns for 2022-2024
+    24: "90d", // S24 Childcare §45F — facility/program establishment
+};
+// ---------------------------------------------------------------------------
+// Core mapping — engine strategy_analysis entry -> canonical Strategy
+// ---------------------------------------------------------------------------
+function mapAnalysisToStrategy(sa, idx, pc) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const ct = ((_a = sa.calculation_trace) !== null && _a !== void 0 ? _a : {});
+    const ci = pc === null || pc === void 0 ? void 0 : pc.confidence_interval;
+    // Dollar amounts: prefer preComputed CI, then calculation_trace CI
+    const lo = ci ? Math.round(ci.low) : Math.round((_c = (_b = ct.confidence_interval) === null || _b === void 0 ? void 0 : _b.low) !== null && _c !== void 0 ? _c : 0);
+    const hi = ci ? Math.round(ci.high) : Math.round((_e = (_d = ct.confidence_interval) === null || _d === void 0 ? void 0 : _d.high) !== null && _e !== void 0 ? _e : 0);
+    const strategyNumber = parseStrategyNumber(sa.strategy_id);
+    const cat = strategyNumber !== null ? ((_f = CATEGORY_BY_RANK.get(strategyNumber)) !== null && _f !== void 0 ? _f : "income") : "income";
+    const staticNarrative = strategyNumber !== null ? strategyNarrative_1.STRATEGY_NARRATIVE[strategyNumber] : undefined;
+    // Source documents from calculation_trace
+    const sourceDocuments = Array.isArray(ct.source_documents) ? ct.source_documents : undefined;
+    const specialistNote = typeof ct.specialist_note === "string" && ct.specialist_note.trim() !== ""
+        ? ct.specialist_note
+        : ((_g = staticNarrative === null || staticNarrative === void 0 ? void 0 : staticNarrative.whySpecialist) !== null && _g !== void 0 ? _g : undefined);
+    const positionStrength = typeof ct.position_strength === "string" ? ct.position_strength : undefined;
+    const authority = typeof ct.irs_cite === "string" ? ct.irs_cite : undefined;
+    const formsFromTrace = Array.isArray(ct.forms_required)
+        ? ct.forms_required.join(", ")
+        : undefined;
+    const priority = (sa.priority_tier || "MEDIUM").toUpperCase();
+    // Deterministic bucket from static map; falls back to "30d" for unknown strategies.
+    const timelineBucket = TIMELINE_BUCKET_BY_STRATEGY[strategyNumber !== null && strategyNumber !== void 0 ? strategyNumber : 0] || "30d";
     return {
         rank: idx + 1,
-        code: (_l = sa.strategy_id) !== null && _l !== void 0 ? _l : `S${idx + 1}`,
-        name: (_m = sa.strategy_name) !== null && _m !== void 0 ? _m : humanize((_o = sa.strategy_id) !== null && _o !== void 0 ? _o : `Strategy ${idx + 1}`),
-        cat: "income",
-        priority: (((_p = sa.priority) !== null && _p !== void 0 ? _p : "MEDIUM").toUpperCase()),
-        score: Math.round(weightedScore),
+        strategyNumber: strategyNumber !== null && strategyNumber !== void 0 ? strategyNumber : undefined,
+        code: (_h = (strategyNumber !== null ? CODE_BY_RANK.get(strategyNumber) : undefined)) !== null && _h !== void 0 ? _h : sa.strategy_id,
+        name: sa.strategy_name,
+        cat,
+        priority,
+        score: sa.weighted_score != null
+            ? Math.min(Math.round((sa.weighted_score / 25) * 100), 100)
+            : (priority === "HIGH" ? 85 : priority === "MEDIUM" ? 70 : 55),
         entities: [],
         lo,
         hi,
-        timeline: timelineBucket === "now" ? "Act now" : timelineBucket === "30d" ? "Within 30 days" : "Within 90 days",
+        timeline: timelineBucket === "now" ? "This week" : timelineBucket === "30d" ? "Within 30 days" : timelineBucket === "filing" ? "At filing" : "Within 90 days",
         timelineBucket,
-        clientBrief: (_q = sa.why_it_applies) !== null && _q !== void 0 ? _q : "Your preparer will review this strategy and include the analysis in your engagement report.",
-        action: (_r = sa.next_step) !== null && _r !== void 0 ? _r : "Work with your CPA to implement this strategy.",
-        forms: Array.isArray(ct.forms_required) ? ct.forms_required.join(", ") : undefined,
-        abstract: sa.why_it_applies,
-        warning: (_s = sa.risk_disclosure) !== null && _s !== void 0 ? _s : null,
-        sources: [],
-        trace: [],
-        cost: undefined,
-        sourceDocuments: Array.isArray(ct.source_documents) ? ct.source_documents : undefined,
-        positionStrength: ct.position_strength,
-        specialistNote: ct.specialist_note,
-        authority: ct.irs_cite,
-        quickWin: (_t = sa.quick_win) !== null && _t !== void 0 ? _t : false,
+        abstract: sa.engagement_recommendation || "",
+        warning: (_j = sa.risk_disclosure) !== null && _j !== void 0 ? _j : null,
+        forms: formsFromTrace,
+        authority,
+        sourceDocuments,
+        specialistNote,
+        positionStrength,
+        quickWin: sa.quick_win,
     };
 }
-function useEngineOutput(engineOutput) {
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+function useEngineOutput(engineOutput, preComputed) {
     return (0, react_1.useMemo)(() => {
-        const analysis = engineOutput === null || engineOutput === void 0 ? void 0 : engineOutput.strategy_analysis;
-        if (!Array.isArray(analysis) || analysis.length === 0)
+        var _a;
+        if (!engineOutput)
+            return null;
+        const strategyAnalysis = engineOutput.strategy_analysis;
+        if (!Array.isArray(strategyAnalysis) || strategyAnalysis.length === 0)
+            return null;
+        const pcResults = (_a = preComputed === null || preComputed === void 0 ? void 0 : preComputed.results) !== null && _a !== void 0 ? _a : {};
+        // Filter: only include strategies where the formula engine returned COMPLETE
+        // OR the reconciler tagged _reconciledPreComputed: true.
+        const validated = strategyAnalysis.filter((sa) => {
+            const pc = pcResults[sa.strategy_id];
+            if ((pc === null || pc === void 0 ? void 0 : pc.status) === "COMPLETE")
+                return true;
+            if (sa._reconciledPreComputed === true)
+                return true;
+            return false;
+        });
+        if (validated.length === 0)
             return null;
-        const strategies = analysis.map((sa, idx) => mapSingleStrategy(sa, idx));
+        // Map to canonical Strategy[]
+        const strategies = validated.map((sa, idx) => {
+            const pc = pcResults[sa.strategy_id];
+            return mapAnalysisToStrategy(sa, idx, pc);
+        });
+        // Build ComputedMap keyed by rank (1-based index matching strategies array)
         const computedMap = new Map();
         for (const s of strategies) {
-            computedMap.set(s.rank, { lo: s.lo, hi: s.hi });
+            computedMap.set(s.rank, {
+                lo: s.lo,
+                hi: s.hi,
+                sources: s.sources,
+                trace: s.trace,
+            });
         }
         return { strategies, computedMap };
-    }, [engineOutput]);
+    }, [engineOutput, preComputed]);
 }

package/lib/tax-axis/lib/data/nextSteps.js

@@ -16,20 +16,20 @@ exports.NEXT_STEPS = {
     8: "Provide your property appraisal or purchase records. A cost segregation study will identify reclassifiable assets.",
     9: "Increase your payroll HSA deduction this pay period. Your preparer will confirm your remaining contribution room.",
     10: "Start logging business meals with date, attendees, and business purpose. 50% of qualifying meals are deductible.",
-    11: "Review your current professional service expenses with your preparer to ensure all are properly categorized.",
-    12: "Photograph your dedicated workspace and collect mortgage and utility bills for the year.",
-    13: "Your preparer will evaluate your current employee health insurance setup for credit eligibility.",
-    14: "Consider bunching two years of charitable contributions into one year for maximum deduction impact.",
-    15: "Your preparer will file a PTE election with your state. Deadline varies by state.",
-    16: "Your preparer will review your business interest expense for §163(j) optimization.",
-    17: "Discuss year-end timing of income and expenses with your preparer before December.",
-    18: "Identify qualifying capital gains and potential Opportunity Zone investments with your advisor.",
-    19: "Have your commercial property evaluated for energy efficiency certification.",
-    20: "Your preparer will review your current accounting method for optimization opportunities.",
-    21: "Provide your POS tip reporting data. Your preparer will calculate the deduction.",
-    22: "Provide your payroll overtime summary. Your preparer will calculate the OBBBA deduction.",
+    11: "Photograph your dedicated workspace and collect mortgage, insurance, and utility bills for the year. Your preparer will compare actual vs. simplified methods.",
+    12: "Your preparer will draft an accountable plan document and board resolution for tax-free reimbursement of qualifying employee business expenses.",
+    13: "Document fair market rental rates for your home and schedule qualifying business use days. Your preparer will prepare the rental agreement and FMV documentation.",
+    14: "Document bona fide job duties and market-rate wages for family members working in the business. Your preparer will set up proper payroll documentation.",
+    15: "Your preparer will evaluate your state's pass-through entity election and calculate the federal deduction benefit versus your current SALT position.",
+    16: "Your preparer will assess qualifying energy-efficient commercial building improvements and determine applicable deduction or credit tiers.",
+    17: "Your preparer will compare standard mileage rate versus actual expense methods and evaluate heavy SUV §179 eligibility for your business vehicles.",
+    18: "Your preparer will review group-term life insurance, disability, and other employer-provided coverage for tax-efficient structuring under IRC employer benefit rules.",
+    19: "Your preparer will evaluate qualifying real property exchanges and coordinate identification and exchange period deadlines with a qualified intermediary.",
+    20: "Your preparer will verify qualified small business stock eligibility, holding period requirements, and the $10M or 10x-basis exclusion limit for capital gains.",
+    21: "Your preparer will calculate the OBBBA qualified tip income deduction for eligible tipped employees and verify documentation requirements.",
+    22: "Your preparer will evaluate OBBBA overtime pay deduction eligibility and calculate the incremental tax deduction for qualifying overtime wages.",
     23: "Your preparer will review prior-year R&E amortization for catch-up eligibility.",
-    24: "Document your employer-provided childcare facilities or referral services.",
+    24: "Your preparer will evaluate employer-provided childcare facility or referral service expenditures and calculate the 25% qualified expenditure credit.",
     25: "Your preparer will evaluate Trump Account eligibility and optimal contribution levels.",
 };
 exports.INTERACTION_PAIRS = [[1, 4], [1, 7], [2, 3]];

package/lib/tax-axis/lib/data/sourceDescriptions.js

@@ -17,7 +17,10 @@ exports.SOURCE_DESC = {
     "§223": "Health Savings Account contributions for HDHP-covered taxpayers",
     "§274": "Business meal deductions, generally limited to 50% of qualifying expenses",
     "§162": "Ordinary and necessary business expenses",
+    "§62": "Accountable plan reimbursements for qualifying employee business expenses under an employer-maintained plan",
     "§280A": "Home office deduction for the business use of a residence",
+    "§280A(g)": "Augusta Rule: exclusion of rental income for personal residence rented 14 days or fewer per year",
+    "§73": "Employment of family members; wage deduction and FICA/FUTA savings for qualifying family employees",
     "§45R": "Small employer health insurance credit",
     "§170": "Charitable contribution deductions",
     "OBBBA §70109": "Pass-through entity tax election workaround for the SALT cap",
@@ -26,6 +29,9 @@ exports.SOURCE_DESC = {
     "§1400Z": "Qualified Opportunity Zone capital gains deferral",
     "§179D": "Energy efficient commercial buildings deduction",
     "§446": "Permissible accounting methods and changes",
+    "§79, §264": "Group-term life insurance exclusion and employer-owned life insurance tax treatment",
+    "§1031": "Like-kind exchange deferral of recognized gain on qualifying real property dispositions",
+    "§1202": "Qualified Small Business Stock gain exclusion: up to $10M or 10x adjusted basis for qualifying C-Corp stock held 5+ years",
     "OBBBA": "OBBBA-introduced deductions and credits (Qualified Tips, Overtime Pay, Trump Accounts)",
     "§174A": "OBBBA-restored full expensing for domestic research and experimental expenditures",
     "§45F": "Employer-provided childcare facilities and services credit",

package/lib/tax-axis/lib/documentFieldCatalog.d.ts

@@ -1,13 +1,18 @@
-export interface FieldDef {
-    label: string;
+export interface CatalogFieldDef {
+    label?: string;
     sourceRef?: string;
 }
 export interface CatalogSection {
     head: string;
     fields: string[];
 }
-export interface DocumentCatalogEntry {
+export interface CatalogEntry {
     sections: CatalogSection[];
-    fields: Record<string, FieldDef>;
+    fields: Record<string, CatalogFieldDef>;
 }
-export declare const DOCUMENT_FIELD_CATALOG: Record<string, DocumentCatalogEntry>;
+/**
+ * Keyed by documentType string returned by the backend in parsedData.documentType.
+ * When DocumentReviewModal receives parsedData, it looks up the documentType here
+ * to get section groupings and field labels. Falls back to flat rendering if no entry.
+ */
+export declare const DOCUMENT_FIELD_CATALOG: Record<string, CatalogEntry>;