@uwmd/core 2.8.0 → 2.10.0

package/dist/validator.js

@@ -2,13 +2,13 @@
 // Spec: UW_FORMAT_SPEC_v1.md Part V
 import { DEFAULT_THRESHOLDS, SOURCE_TAGS } from './types.js';
 import { getSection, getSectionVariant, deepGet } from './parser.js';
-import { BUILTIN_REMEDIATIONS, BUILTIN_INCOMPLETE_DATA_POLICIES, lookupIncompleteDataPolicy, getSizeIntensive, DEAL_UNDERWRITING_PROFILE, parseActorSource, isSupportedLocale, STAGE_REQUIREMENTS, requiredSectionsFor, CROSS_CHECK_RULE_IDS, RETURN_TAX_BASES, DEFAULT_RETURN_TAX_BASIS, } from './protocol.js';
+import { BUILTIN_REMEDIATIONS, BUILTIN_INCOMPLETE_DATA_POLICIES, lookupIncompleteDataPolicy, getSizeIntensive, DEAL_UNDERWRITING_PROFILE, parseActorSource, isSupportedLocale, isCurrencyCode, STAGE_REQUIREMENTS, requiredSectionsFor, CROSS_CHECK_RULE_IDS, RETURN_TAX_BASES, DEFAULT_RETURN_TAX_BASIS, } from './protocol.js';
 import { EXTERNAL_ANNOTATION_KEY } from './composition.js';
 import { UW_LITE_SOURCE_EXTENSION } from './lite-bridge.js';
 import { readGapsContent } from './gaps.js';
 import { LEASE_UP_STABILIZED_TOLERANCE } from './lease-up.js';
 import { checkLeaseUpContent } from './lease-up-structure.js';
-import { CASH_FLOW_KINDS } from './cash-flow-series.js';
+import { CASH_FLOW_KINDS, CASH_FLOW_VERIFY_DECIMALS, quantizeAtDecimals } from './cash-flow-series.js';
 import { isDayCountConvention, parseISODate } from './calc/day-count.js';
 import { parseAssetClass, declaredModuleDependencies } from './asset-class.js';
 import { isV2File } from './meta-shape.js';
@@ -105,7 +105,9 @@ export function validateUWFile(parsed, thresholdOverrides) {
     checkSizeIntensive(parsed, issues, ledger);
     checkSectionReadiness(parsed, issues, ledger);
     checkReturnsTaxBasis(parsed, issues);
+    checkTaxBasis(parsed, issues);
     checkLocale(parsed, issues);
+    checkCurrencyIdentity(parsed, issues);
     checkAssetClassIdentifier(parsed, issues);
     checkMetaIntegrity(parsed, issues);
     checkMetaShape(parsed, issues);
@@ -636,6 +638,245 @@ function checkReturnsTaxBasis(parsed, issues) {
         value: v,
     });
 }
+// ─── §4.5 / §4.9 Tax abatements and reassessment basis (RFC 0053) ────────────
+//
+// Every rule here checks a figure the author stated. Nothing is derived, no
+// jurisdiction rules are inferred, and the exit-value/terminal-tax circularity
+// is left to the author — the calc engine has no iteration and this adds none.
+// Quantize with the §VIII.5 helper the cash-flow verifier exports rather than
+// keeping a second copy of the rounding rule.
+/** What caused the reassessment; `none` means none applies. */
+export const REASSESSMENT_TRIGGERS = Object.freeze([
+    'sale', 'construction_completion', 'statutory_cycle', 'none',
+]);
+export const TAX_ABATEMENT_KINDS = Object.freeze([
+    'exemption', 'freeze', 'pilot', 'phase_in', 'credit',
+]);
+const TAX_PATH = 'expenses.real_estate_taxes';
+const CURRENCY_DP = CASH_FLOW_VERIFY_DECIMALS.currency;
+function taxIssue(issues, code, section, field, message, value) {
+    issues.push({ code, severity: 'error', section, field, message, ...(value !== undefined ? { value } : {}) });
+}
+const finiteNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const sameMoney = (a, b) => quantizeAtDecimals(a, CURRENCY_DP) === quantizeAtDecimals(b, CURRENCY_DP);
+/**
+ * The shape shared by the `noi_model` reassessment and the `dcf` terminal tax.
+ * Returns the quantum the stated expense must be rounded at, or null when the
+ * object is too malformed to check any further.
+ */
+function checkReassessment(r, issues, section, base) {
+    const trigger = r['trigger'];
+    if (typeof trigger !== 'string' || !REASSESSMENT_TRIGGERS.includes(trigger)) {
+        taxIssue(issues, 'TAX-01', section, `${base}.trigger`, `TAX-01: reassessment.trigger must be one of ${REASSESSMENT_TRIGGERS.join(', ')}`, trigger);
+        return null;
+    }
+    const assessed = r['assessed_value'];
+    const millage = r['millage_rate'];
+    const indicated = r['indicated_tax'];
+    let ok = true;
+    for (const [key, v] of [['assessed_value', assessed], ['millage_rate', millage], ['indicated_tax', indicated]]) {
+        if (!finiteNum(v)) {
+            taxIssue(issues, 'TAX-01', section, `${base}.${key}`, `TAX-01: reassessment.${key} must be a finite number`, v);
+            ok = false;
+        }
+    }
+    if (!ok)
+        return null;
+    // TAX-01: the assessed value follows from the basis and ratio when both are stated.
+    const basis = r['value_basis'];
+    const ratio = r['assessment_ratio'];
+    if (basis !== undefined || ratio !== undefined) {
+        if (!finiteNum(basis) || !finiteNum(ratio)) {
+            taxIssue(issues, 'TAX-01', section, `${base}.assessment_ratio`, 'TAX-01: value_basis and assessment_ratio are stated together or not at all');
+        }
+        else if (!sameMoney(basis * ratio, assessed)) {
+            taxIssue(issues, 'TAX-01', section, `${base}.assessed_value`, `TAX-01: assessed_value ${assessed} must equal value_basis x assessment_ratio (${quantizeAtDecimals(basis * ratio, CURRENCY_DP)})`, assessed);
+        }
+    }
+    // TAX-02: the indicated tax follows from the assessed value and the millage.
+    if (!sameMoney(indicated, assessed * millage)) {
+        taxIssue(issues, 'TAX-02', section, `${base}.indicated_tax`, `TAX-02: indicated_tax ${indicated} must equal assessed_value x millage_rate (${quantizeAtDecimals(assessed * millage, CURRENCY_DP)})`, indicated);
+    }
+    const round = r['round_to_decimals'];
+    if (round !== undefined && !Number.isSafeInteger(round)) {
+        taxIssue(issues, 'TAX-03', section, `${base}.round_to_decimals`, 'TAX-03: round_to_decimals must be an integer; it may be negative to round to a magnitude', round);
+        return null;
+    }
+    return round === undefined ? CURRENCY_DP : round;
+}
+function checkAbatement(a, issues, section, base, stated) {
+    const kind = a['kind'];
+    if (typeof kind !== 'string' || !TAX_ABATEMENT_KINDS.includes(kind)) {
+        taxIssue(issues, 'TAX-06', section, `${base}.kind`, `TAX-06: abatement.kind must be one of ${TAX_ABATEMENT_KINDS.join(', ')}`, kind);
+        return;
+    }
+    const schedule = a['schedule'];
+    if (!Array.isArray(schedule) || schedule.length === 0) {
+        taxIssue(issues, 'TAX-05', section, `${base}.schedule`, 'TAX-05: abatement.schedule must be a nonempty array');
+        return;
+    }
+    const periods = [];
+    let shapeOk = true;
+    for (const [i, row] of schedule.entries()) {
+        const at = `${base}.schedule[${i}]`;
+        if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+            taxIssue(issues, 'TAX-05', section, at, 'TAX-05: each schedule entry must be an object');
+            shapeOk = false;
+            continue;
+        }
+        const e = row;
+        const period = e['period'];
+        if (typeof period !== 'string' || taxPeriodKind(period) === null) {
+            taxIssue(issues, 'TAX-05', section, `${at}.period`, 'TAX-05: period must be an RFC 0041 selector (Y1+, YYYY-Qn, YYYY-MM, or YYYY-MM-DD)', period);
+            shapeOk = false;
+            continue;
+        }
+        periods.push(period);
+        const full = e['full_tax'];
+        const abated = e['abated_tax'];
+        if (!finiteNum(full) || !finiteNum(abated)) {
+            taxIssue(issues, 'TAX-06', section, at, 'TAX-06: full_tax and abated_tax must both be finite numbers');
+            shapeOk = false;
+            continue;
+        }
+        if (abated < 0 || full < 0) {
+            taxIssue(issues, 'TAX-06', section, at, 'TAX-06: full_tax and abated_tax must be nonnegative', abated);
+        }
+        else if (abated > full) {
+            taxIssue(issues, 'TAX-06', section, `${at}.abated_tax`, `TAX-06: abated_tax ${abated} cannot exceed full_tax ${full}`, abated);
+        }
+    }
+    if (!shapeOk)
+        return;
+    // TAX-05: one granularity, strictly increasing, no duplicates.
+    const kinds = new Set(periods.map(p => taxPeriodKind(p)));
+    if (kinds.size > 1) {
+        taxIssue(issues, 'TAX-05', section, `${base}.schedule`, `TAX-05: an abatement schedule uses one period granularity (found ${[...kinds].sort().join(', ')})`);
+        return;
+    }
+    for (let i = 1; i < periods.length; i++) {
+        if (periods[i - 1].localeCompare(periods[i], 'en', { numeric: true }) >= 0) {
+            taxIssue(issues, 'TAX-05', section, `${base}.schedule[${i}].period`, `TAX-05: schedule periods must strictly increase (${periods[i - 1]} then ${periods[i]})`, periods[i]);
+            return;
+        }
+    }
+    // TAX-06: a freeze holds the unabated tax nondecreasing across the schedule.
+    if (kind === 'freeze') {
+        for (let i = 1; i < schedule.length; i++) {
+            const prev = schedule[i - 1]['full_tax'];
+            const cur = schedule[i]['full_tax'];
+            if (cur < prev) {
+                taxIssue(issues, 'TAX-06', section, `${base}.schedule[${i}].full_tax`, `TAX-06: a freeze holds full_tax nondecreasing (${prev} then ${cur})`, cur);
+                return;
+            }
+        }
+    }
+    // TAX-07: the stabilized snapshot ties to one named period of the schedule.
+    const stabilized = a['stabilized_period'];
+    if (stabilized === undefined)
+        return;
+    if (typeof stabilized !== 'string') {
+        taxIssue(issues, 'TAX-07', section, `${base}.stabilized_period`, 'TAX-07: stabilized_period must be a period selector naming a schedule entry', stabilized);
+        return;
+    }
+    const at = periods.indexOf(stabilized);
+    if (at === -1) {
+        taxIssue(issues, 'TAX-07', section, `${base}.stabilized_period`, `TAX-07: stabilized_period ${stabilized} does not name a period in the schedule`, stabilized);
+        return;
+    }
+    if (!finiteNum(stated))
+        return;
+    const abated = schedule[at]['abated_tax'];
+    if (!sameMoney(stated, abated)) {
+        taxIssue(issues, 'TAX-07', section, `${TAX_PATH}.value`, `TAX-07: the stated tax ${stated} must equal the abated tax ${abated} for stabilized_period ${stabilized}`, stated);
+    }
+}
+/** The RFC 0041 selector families, or null when the string is not one. */
+function taxPeriodKind(p) {
+    if (/^Y[1-9]\d*$/.test(p))
+        return 'holding_year';
+    if (/^\d{4}-Q[1-4]$/.test(p))
+        return 'quarter';
+    if (/^\d{4}-(0[1-9]|1[0-2])$/.test(p))
+        return 'month';
+    if (/^\d{4}-\d{2}-\d{2}$/.test(p) && parseISODate(p))
+        return 'date';
+    return null;
+}
+function checkTaxBasis(parsed, issues) {
+    const noi = resolveCrossCheckSection(parsed, 'noi_model').block;
+    if (noi) {
+        const tax = deepGet(noi.content, TAX_PATH);
+        if (tax !== null && typeof tax === 'object' && !Array.isArray(tax)) {
+            const t = tax;
+            const stated = t['value'];
+            const r = t['reassessment'];
+            if (r !== undefined) {
+                if (r === null || typeof r !== 'object' || Array.isArray(r)) {
+                    taxIssue(issues, 'TAX-01', 'noi_model', `${TAX_PATH}.reassessment`, 'TAX-01: reassessment must be an object when stated', r);
+                }
+                else {
+                    const rr = r;
+                    const dp = checkReassessment(rr, issues, 'noi_model', `${TAX_PATH}.reassessment`);
+                    // TAX-03: the stated expense is the indicated tax at the declared quantum.
+                    if (dp !== null && finiteNum(stated) && finiteNum(rr['indicated_tax'])) {
+                        const rounded = quantizeAtDecimals(rr['indicated_tax'], dp);
+                        if (!sameMoney(stated, rounded)) {
+                            taxIssue(issues, 'TAX-03', 'noi_model', `${TAX_PATH}.value`, `TAX-03: the stated tax ${stated} must equal indicated_tax rounded at ${dp} decimals (${rounded})`, stated);
+                        }
+                    }
+                    // TAX-04: the legacy boolean has to agree with the typed trigger.
+                    const flag = t['sale_triggers_reassessment'];
+                    if (typeof flag === 'boolean' && flag !== (rr['trigger'] === 'sale')) {
+                        taxIssue(issues, 'TAX-04', 'noi_model', `${TAX_PATH}.sale_triggers_reassessment`, `TAX-04: sale_triggers_reassessment ${flag} disagrees with reassessment.trigger ${JSON.stringify(rr['trigger'])}`, flag);
+                    }
+                }
+            }
+            const a = t['abatement'];
+            if (a !== undefined) {
+                if (a === null || typeof a !== 'object' || Array.isArray(a)) {
+                    taxIssue(issues, 'TAX-06', 'noi_model', `${TAX_PATH}.abatement`, 'TAX-06: abatement must be an object when stated', a);
+                }
+                else {
+                    checkAbatement(a, issues, 'noi_model', `${TAX_PATH}.abatement`, stated);
+                }
+            }
+        }
+    }
+    // The terminal tax: the next buyer's, after this sale reassesses at the exit
+    // price. No arithmetic is asserted over exit_noi — deriveDCF leaves
+    // exit_value_gross an input because it capitalizes an unstored forward NOI.
+    const dcf = resolveCrossCheckSection(parsed, 'dcf').block;
+    if (!dcf)
+        return;
+    const tt = deepGet(dcf.content, 'exit_analysis.terminal_tax');
+    if (tt === undefined)
+        return;
+    const base = 'exit_analysis.terminal_tax';
+    if (tt === null || typeof tt !== 'object' || Array.isArray(tt)) {
+        taxIssue(issues, 'TAX-01', 'dcf', base, 'TAX-01: terminal_tax must be an object when stated', tt);
+        return;
+    }
+    const t = tt;
+    checkReassessment(t, issues, 'dcf', base);
+    if (typeof t['in_exit_noi'] !== 'boolean') {
+        taxIssue(issues, 'TAX-08', 'dcf', `${base}.in_exit_noi`, 'TAX-08: terminal_tax.in_exit_noi must state whether this tax is already inside exit_noi', t['in_exit_noi']);
+    }
+    // TAX-08: the next buyer is reassessed at what they pay, so the basis is the
+    // exit value — unless the author says in words why it is not.
+    if (t['trigger'] !== 'sale')
+        return;
+    const why = t['value_basis_differs_because'];
+    if (typeof why === 'string' && why.trim().length > 0)
+        return;
+    const gross = deepGet(dcf.content, 'exit_analysis.exit_value_gross');
+    const basis = t['value_basis'];
+    if (!finiteNum(gross) || !finiteNum(basis))
+        return;
+    if (!sameMoney(basis, gross)) {
+        taxIssue(issues, 'TAX-08', 'dcf', `${base}.value_basis`, `TAX-08: terminal_tax.value_basis ${basis} must equal exit_value_gross ${gross} for a sale trigger, or state value_basis_differs_because`, basis);
+    }
+}
 // ─── §4.23 Mixed-use components (RFC 0019) ───────────────────────────────────
 // The eight income classes admissible as a mixed-use component. `land` is
 // excluded (its NOI model nets negative) and `mixed_use` cannot nest in itself.
@@ -858,6 +1099,30 @@ function checkStackContent(content, section, prefix, issues) {
                 issues.push({ code: 'CS-02', severity: 'error', section, field: `${prefix}${label}.rate`, message: `CS-02: common_equity tranche ${label} must not state a rate` });
             }
         }
+        // CS-02b: a split coupon is one preferred-equity tranche with two
+        // explicitly typed rate components. Keep the field-presence rule here,
+        // beside CS-02, so schema-valid and hand-built ParsedUWFile inputs receive
+        // the same refusal.
+        const hasCashRate = Object.prototype.hasOwnProperty.call(t, 'cash_rate');
+        const hasAccruedRate = Object.prototype.hasOwnProperty.call(t, 'accrued_rate');
+        if (t['accrual'] === 'split') {
+            if (cls !== 'preferred_equity') {
+                issues.push({ code: 'CS-02b', severity: 'error', section, field: `${prefix}${label}.accrual`, message: `CS-02b: split accrual is supported only for preferred_equity tranche ${label}` });
+            }
+            if (!hasCashRate || !Number.isFinite(t['cash_rate'])) {
+                issues.push({ code: 'CS-02b', severity: 'error', section, field: `${prefix}${label}.cash_rate`, message: `CS-02b: split tranche ${label} must state a numeric cash_rate` });
+            }
+            if (!hasAccruedRate || !Number.isFinite(t['accrued_rate'])) {
+                issues.push({ code: 'CS-02b', severity: 'error', section, field: `${prefix}${label}.accrued_rate`, message: `CS-02b: split tranche ${label} must state a numeric accrued_rate` });
+            }
+            if (hasRate && Number.isFinite(t['cash_rate']) && Number.isFinite(t['accrued_rate'])
+                && t['rate'] !== t['cash_rate'] + t['accrued_rate']) {
+                issues.push({ code: 'CS-02b', severity: 'error', section, field: `${prefix}${label}.rate`, message: `CS-02b: split tranche ${label}.rate must equal cash_rate + accrued_rate` });
+            }
+        }
+        else if (hasCashRate || hasAccruedRate) {
+            issues.push({ code: 'CS-02b', severity: 'error', section, field: `${prefix}${label}.accrual`, message: `CS-02b: cash_rate and accrued_rate are permitted only when tranche ${label} uses accrual: "split"` });
+        }
         // A waterfall smuggled in at the tranche level (promote/hurdle/catch-up).
         for (const key of Object.keys(t)) {
             if (WATERFALL_MARKERS.includes(key)) {
@@ -1291,6 +1556,14 @@ function checkWaterfallContent(content, variant, parsed, issues) {
                         irrOk = true;
                     }
                 }
+                if (t.hurdle_mode != null) {
+                    if (t.hurdle_mode !== 'both' && t.hurdle_mode !== 'any') {
+                        wf01(`tiers[${i}].hurdle_mode`, 'hurdle_mode must be "both" or "any"');
+                    }
+                    else if (t.until_lp_em == null || t.until_lp_irr == null) {
+                        wf01(`tiers[${i}].hurdle_mode`, 'hurdle_mode is only permitted when both until_lp_em and until_lp_irr are stated');
+                    }
+                }
                 if (t.until_lp_em != null || t.until_lp_irr != null) {
                     if ((emOk || irrOk) && !(typeof t.lp_share === 'number' && t.lp_share > 0)) {
                         wf01(`tiers[${i}].lp_share`, 'a capped split must pay the LP (lp_share > 0) or the cap can never bind');
@@ -1383,6 +1656,19 @@ function checkLocale(parsed, issues) {
         value: String(declared),
     });
 }
+// ─── Document currency identity (RFC 0046) ──────────────────────────────────
+function checkCurrencyIdentity(parsed, issues) {
+    const declared = parsed.frontmatter.currency_code;
+    if (declared == null)
+        return; // absent preserves legacy symbol behavior
+    if (isCurrencyCode(declared))
+        return;
+    issues.push({
+        code: 'CUR-01', severity: 'error', field: 'currency_code',
+        message: `CUR-01: currency_code ${JSON.stringify(declared)} is not three uppercase ASCII letters; currency identity is never inferred from locale or a display symbol`,
+        value: declared,
+    });
+}
 // ─── Asset-class identifier (RFC 0003) ───────────────────────────────────────
 /**
  * The identifier itself, independent of whether any module is loaded.