@uwmd/core 2.6.2 → 2.8.0

package/dist/validator.js

@@ -2,15 +2,18 @@
 // 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, CROSS_CHECK_VARIANT_PREFERENCE, RETURN_TAX_BASES, DEFAULT_RETURN_TAX_BASIS, } from './protocol.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 { EXTERNAL_ANNOTATION_KEY } from './composition.js';
 import { UW_LITE_SOURCE_EXTENSION } from './lite-bridge.js';
 import { readGapsContent } from './gaps.js';
-import { leaseUpPeriodOrdinal, LEASE_UP_STABILIZED_TOLERANCE } from './lease-up.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 { isDayCountConvention, parseISODate } from './calc/day-count.js';
 import { parseAssetClass, declaredModuleDependencies } from './asset-class.js';
 import { isV2File } from './meta-shape.js';
+import { checkPeriodSeries } from './period-validation.js';
+import { hasBlockRole, isBlockRole, resolveRoleBlock } from './block-roles.js';
 // ─── BUILTIN_REMEDIATIONS lookup (UW_PROTOCOL_v1.md §III.6) ──────────────────
 //
 // Validator constructs inline messages with deal-specific values, but the
@@ -106,6 +109,8 @@ export function validateUWFile(parsed, thresholdOverrides) {
     checkAssetClassIdentifier(parsed, issues);
     checkMetaIntegrity(parsed, issues);
     checkMetaShape(parsed, issues);
+    checkBlockRoles(parsed, issues);
+    checkPeriodSeries(parsed, issues);
     checkSourceVocabulary(parsed, issues);
     checkScopeReadiness(parsed, issues);
     checkDataQuality(parsed, issues);
@@ -116,7 +121,8 @@ export function validateUWFile(parsed, thresholdOverrides) {
         const codes = [...entry.codes].sort();
         issues.push({
             code: 'CC-16', severity: 'info', section: sectionId,
-            message: `CC-16: ${sectionId} is present as ${entry.variants.length} variants (${entry.variants.join(', ')}) and none is named default or base; ${codes.join(', ')} ${codes.length === 1 ? 'was' : 'were'} skipped — name a default variant or state the section once (§5.3, RFC 0037)`,
+            ...(entry.detail ? { remediation: 'Resolve the reported role collision or declare an eligible property-level block; component blocks cannot serve as the property total.' } : {}),
+            message: entry.detail ? `CC-16: ${sectionId}: ${entry.detail}; could not resolve for ${codes.join(', ')} (§5.3, RFC 0040)` : `CC-16: ${sectionId} is present as ${entry.variants.length} variants (${entry.variants.join(', ')}) and none is named default or base; ${codes.join(', ')} ${codes.length === 1 ? 'was' : 'were'} skipped — name a default variant or state the section once (§5.3, RFC 0037)`,
             value: entry.variants,
         });
     }
@@ -266,7 +272,7 @@ function checkFinancialValidity(parsed, t, issues) {
     }
 }
 function newCoverageLedger() {
-    return { coverage: {}, unresolvable: new Map() };
+    return { coverage: {}, unresolvable: new Map(), resolutions: {} };
 }
 function markEvaluated(ledger, code) {
     ledger.coverage[code] = { status: 'evaluated' };
@@ -276,8 +282,8 @@ function markSkipped(ledger, code, reason, detail) {
         return;
     ledger.coverage[code] = { status: 'skipped', reason, ...(detail ? { detail } : {}) };
 }
-function noteUnresolvable(ledger, sectionId, variants, code) {
-    const entry = ledger.unresolvable.get(sectionId) ?? { variants, codes: new Set() };
+function noteUnresolvable(ledger, sectionId, variants, code, detail) {
+    const entry = ledger.unresolvable.get(sectionId) ?? { variants, codes: new Set(), ...(detail ? { detail } : {}) };
     entry.codes.add(code);
     ledger.unresolvable.set(sectionId, entry);
 }
@@ -287,26 +293,50 @@ function orderedCoverage(ledger) {
     for (const code of CROSS_CHECK_RULE_IDS) {
         const entry = ledger.coverage[code];
         if (entry)
-            out[code] = entry;
+            out[code] = { ...entry, ...(ledger.resolutions[code] ? { resolutions: ledger.resolutions[code] } : {}) };
     }
     return out;
 }
-function resolveCrossCheckSection(parsed, sectionId, preferred = []) {
+function resolveCrossCheckSection(parsed, sectionId, preferred = [], code, ledger) {
+    const r = resolveRoleBlock(parsed.sections[sectionId], sectionId, preferred, code);
+    if (r.state === 'resolved' && r.evidence && code && ledger) {
+        ledger.resolutions[code] ??= {};
+        ledger.resolutions[code][sectionId] = r.evidence;
+    }
+    return r;
+}
+/** Preserve legacy direct-read behavior unless the section opts into roles. */
+function roleAwareDirectRead(parsed, sectionId, code, ledger) {
     const entry = parsed.sections[sectionId];
-    if (!entry)
-        return { state: 'absent', block: null };
-    if (!isVariantMap(entry))
-        return { state: 'resolved', block: entry };
-    const map = entry;
-    for (const key of [...preferred, ...CROSS_CHECK_VARIANT_PREFERENCE]) {
-        const block = map[key];
-        if (block)
-            return { state: 'resolved', block, variant: key };
-    }
-    const keys = Object.keys(map);
-    if (keys.length === 1)
-        return { state: 'resolved', block: map[keys[0]], variant: keys[0] };
-    return { state: 'unresolvable', block: null, variants: keys.sort() };
+    const blocks = !entry ? [] : isVariantMap(entry) ? Object.values(entry) : [entry];
+    if (!blocks.some(hasBlockRole))
+        return getSection(parsed, sectionId);
+    const r = resolveCrossCheckSection(parsed, sectionId, [], code, ledger);
+    if (r.state === 'unresolvable' && code && ledger) {
+        noteUnresolvable(ledger, sectionId, r.variants, code, r.detail);
+        markSkipped(ledger, code, 'variant_unresolvable', sectionId);
+    }
+    return r.block;
+}
+function checkBlockRoles(parsed, issues) {
+    const check = (section, block) => {
+        if (hasBlockRole(block) && !isBlockRole(block.content['_role']))
+            issues.push({
+                code: 'ROLE-01', severity: 'error', section, field: '_role',
+                message: `ROLE-01: ${section}${block.annotation.variant ? ` variant=${block.annotation.variant}` : ''} must declare one valid scalar _role`,
+                value: block.content['_role'],
+            });
+    };
+    for (const [section, entry] of Object.entries(parsed.sections)) {
+        for (const block of isVariantMap(entry) ? Object.values(entry) : [entry])
+            check(section, block);
+    }
+    for (const [section, block] of Object.entries(parsed.extensions))
+        check(section, block);
+    for (const section of ['pipeline_log', 'custom_calculations', 'custom_scenarios']) {
+        for (const block of parsed[section])
+            check(section, block);
+    }
 }
 /**
  * Resolve every section a rule reads. On any failure the rule's skip is
@@ -319,13 +349,13 @@ function requireSections(ledger, parsed, code, needs) {
     for (const need of needs) {
         const sectionId = need[0];
         const preferred = need.length > 1 ? need[1] : [];
-        const r = resolveCrossCheckSection(parsed, sectionId, preferred);
+        const r = resolveCrossCheckSection(parsed, sectionId, preferred, code, ledger);
         if (r.state === 'resolved') {
             out[sectionId] = { block: r.block, ...(r.variant ? { variant: r.variant } : {}) };
             continue;
         }
         if (r.state === 'unresolvable')
-            noteUnresolvable(ledger, sectionId, r.variants, code);
+            noteUnresolvable(ledger, sectionId, r.variants, code, r.detail);
         skip ??= { reason: r.state === 'absent' ? 'section_absent' : 'variant_unresolvable', detail: sectionId };
     }
     if (skip) {
@@ -389,12 +419,12 @@ function checkCrossSectionConsistency(parsed, issues, ledger) {
     // once and agreeing everywhere (RFC 0026 §4.24). Two legs; the rule is
     // evaluated when either leg compared.
     {
-        const su = resolveCrossCheckSection(parsed, 'sources_uses');
-        const ds = resolveCrossCheckSection(parsed, 'debt_structure');
+        const su = resolveCrossCheckSection(parsed, 'sources_uses', [], 'CC-03', ledger);
+        const ds = resolveCrossCheckSection(parsed, 'debt_structure', [], 'CC-03', ledger);
         if (su.state === 'unresolvable')
-            noteUnresolvable(ledger, 'sources_uses', su.variants, 'CC-03');
+            noteUnresolvable(ledger, 'sources_uses', su.variants, 'CC-03', su.detail);
         if (ds.state === 'unresolvable')
-            noteUnresolvable(ledger, 'debt_structure', ds.variants, 'CC-03');
+            noteUnresolvable(ledger, 'debt_structure', ds.variants, 'CC-03', ds.detail);
         const suLoan = su.block ? (num(deepGet(su.block.content, 'sources.loan_amount')) ?? num(deepGet(su.block.content, 'sources.debt_proceeds'))) : undefined;
         const dsLoan = ds.block ? num(deepGet(ds.block.content, 'loan_amount')) : undefined;
         let evaluated = false;
@@ -404,7 +434,7 @@ function checkCrossSectionConsistency(parsed, issues, ledger) {
                 issues.push({ code: 'CC-03', severity: 'error', section: 'sources_uses', field: 'sources.loan_amount', message: `CC-03: Loan amount in Sources & Uses ($${suLoan.toLocaleString()}) does not match Debt Structure loan amount ($${dsLoan.toLocaleString()})`, value: Math.abs(suLoan - dsLoan) });
             }
         }
-        const senior = seniorDebtTranche(parsed);
+        const senior = seniorDebtTranche(parsed, ledger);
         if (senior) {
             const seniorAmount = num(senior['amount']);
             const reference = dsLoan ?? suLoan;
@@ -421,6 +451,7 @@ function checkCrossSectionConsistency(parsed, issues, ledger) {
             markSkipped(ledger, 'CC-03', 'variant_unresolvable', 'sources_uses');
         else if (ds.state === 'unresolvable')
             markSkipped(ledger, 'CC-03', 'variant_unresolvable', 'debt_structure');
+        else if (ledger.coverage['CC-03']?.reason === 'variant_unresolvable') { /* A role-bearing capital stack could not resolve. */ }
         else if (su.state === 'absent')
             markSkipped(ledger, 'CC-03', 'section_absent', 'sources_uses');
         else if (ds.state === 'absent')
@@ -616,7 +647,12 @@ const ADMISSIBLE_COMPONENT_CLASSES = new Set([
 // footing check (property NOI == Σ component NOI), and the section-internal
 // MU-* rules. A no-op for any document without a components section.
 function checkComponents(parsed, issues, ledger) {
-    const components = getSection(parsed, 'components');
+    const components = roleAwareDirectRead(parsed, 'components', 'CC-11', ledger);
+    if (ledger.coverage['CC-11']?.reason === 'variant_unresolvable') {
+        markSkipped(ledger, 'CC-12', 'variant_unresolvable', 'components');
+        ledger.unresolvable.get('components')?.codes.add('CC-12');
+        return;
+    }
     if (!components) {
         markSkipped(ledger, 'CC-11', 'not_applicable', 'no components section');
         markSkipped(ledger, 'CC-12', 'not_applicable', 'no components section');
@@ -700,8 +736,12 @@ function checkComponents(parsed, issues, ledger) {
     // CC-12: property NOI must equal the sum of component NOIs. Only assert footing
     // when every admissible component states a numeric NOI — a missing one is
     // MU-04's job, not a footing mismatch.
-    const noiModel = getSection(parsed, 'noi_model');
-    if (!noiModel)
+    const noiModel = roleAwareDirectRead(parsed, 'noi_model', 'CC-12', ledger);
+    if (ledger.resolutions['CC-11']?.['components']) {
+        ledger.resolutions['CC-12'] ??= {};
+        ledger.resolutions['CC-12']['components'] = ledger.resolutions['CC-11']['components'];
+    }
+    if (!noiModel && !ledger.coverage['CC-12'])
         markSkipped(ledger, 'CC-12', 'section_absent', 'noi_model');
     if (noiModel) {
         const propNOI = deepGet(noiModel.content, 'net_operating_income');
@@ -743,8 +783,8 @@ const WATERFALL_MARKERS = [
     'tiers', 'promote', 'hurdle', 'hurdles', 'catch_up', 'carried_interest',
 ];
 /** The capital_stack `senior_debt` tranche, if the section and tranche exist. */
-function seniorDebtTranche(parsed) {
-    const cs = getSection(parsed, 'capital_stack');
+function seniorDebtTranche(parsed, ledger) {
+    const cs = roleAwareDirectRead(parsed, 'capital_stack', 'CC-03', ledger);
     if (!cs)
         return null;
     const tranches = cs.content['tranches'];
@@ -866,7 +906,12 @@ function checkSizeIntensive(parsed, issues, ledger) {
     }
     // 4. A property section exists — a missing section is a different defect
     //    with a different remedy (RFC 0027, unresolved question 5).
-    const property = getSection(parsed, 'property') ?? getSectionVariant(parsed, 'property', 'default');
+    const propertyEntry = parsed.sections['property'];
+    const roleBearing = propertyEntry && (isVariantMap(propertyEntry) ? Object.values(propertyEntry) : [propertyEntry]).some(hasBlockRole);
+    const property = roleBearing ? roleAwareDirectRead(parsed, 'property', 'CC-13', ledger)
+        : getSection(parsed, 'property') ?? getSectionVariant(parsed, 'property', 'default');
+    if (ledger.coverage['CC-13']?.reason === 'variant_unresolvable')
+        return;
     if (!property) {
         markSkipped(ledger, 'CC-13', 'section_absent', 'property');
         return;
@@ -971,65 +1016,6 @@ function checkCapitalStack(parsed, issues) {
 // variant is checked structurally — a downside scenario with a gapped schedule
 // is just as malformed as a base one. CC-15 reads only the base variant: a
 // downside scenario is *supposed* to disagree with stabilized NOI.
-function checkLeaseUpContent(content, variant, issues) {
-    const section = 'lease_up_schedule';
-    const label = variant === 'default' ? '' : ` (variant "${variant}")`;
-    const granRaw = content['period_granularity'];
-    const granularity = granRaw === 'monthly' || granRaw === 'quarterly' ? granRaw : 'quarterly';
-    if (granRaw !== 'monthly' && granRaw !== 'quarterly') {
-        issues.push({
-            code: 'LU-01', severity: 'error', section, field: 'period_granularity',
-            message: `LU-01: period_granularity${label} must be "monthly" or "quarterly", not ${JSON.stringify(granRaw)}`,
-        });
-    }
-    const schedule = content['schedule'];
-    const rows = Array.isArray(schedule) ? schedule : [];
-    if (!Array.isArray(schedule) || rows.length === 0) {
-        issues.push({
-            code: 'LU-03', severity: 'error', section, field: 'schedule',
-            message: `LU-03: schedule${label} must be a non-empty array of periods`,
-        });
-        return;
-    }
-    // LU-01 (grammar) / LU-02 (strictly increasing, gap-free). One diagnostic
-    // per defect: a row outside the grammar is not also reported as a gap.
-    let prev = null;
-    let grammarBroken = false;
-    for (let i = 0; i < rows.length; i++) {
-        const row = rows[i];
-        const period = row && typeof row === 'object' ? row['period'] : undefined;
-        const ordinal = typeof period === 'string' ? leaseUpPeriodOrdinal(period, granularity) : null;
-        if (ordinal === null) {
-            grammarBroken = true;
-            issues.push({
-                code: 'LU-01', severity: 'error', section, field: `schedule[${i}].period`,
-                message: `LU-01: period ${JSON.stringify(period)}${label} is outside the ${granularity} grammar (${granularity === 'quarterly' ? 'YYYY-Qn' : 'YYYY-MM'})`,
-            });
-            prev = null;
-            continue;
-        }
-        if (prev !== null && ordinal !== prev + 1) {
-            issues.push({
-                code: 'LU-02', severity: 'error', section, field: `schedule[${i}].period`,
-                message: `LU-02: periods${label} must be strictly increasing and gap-free; ${String(period)} does not immediately follow the prior period`,
-            });
-        }
-        prev = ordinal;
-    }
-    // LU-03 (second arm): a stabilization_target earlier than the first period.
-    const target = content['stabilization_target'];
-    if (!grammarBroken && typeof target === 'string') {
-        const first = rows[0]['period'];
-        const targetOrd = leaseUpPeriodOrdinal(target, granularity);
-        const firstOrd = typeof first === 'string' ? leaseUpPeriodOrdinal(first, granularity) : null;
-        if (targetOrd !== null && firstOrd !== null && targetOrd < firstOrd) {
-            issues.push({
-                code: 'LU-03', severity: 'error', section, field: 'stabilization_target',
-                message: `LU-03: stabilization_target ${target}${label} is earlier than the first schedule period ${String(first)}`,
-            });
-        }
-    }
-}
 function checkLeaseUpSchedule(parsed, issues, ledger) {
     const entry = parsed.sections['lease_up_schedule'];
     if (!entry) {
@@ -1065,12 +1051,28 @@ function checkLeaseUpSchedule(parsed, issues, ledger) {
     const base = isVariantMap(entry)
         ? (entry['base'] ?? entry['default'])
         : entry;
-    if (!base)
+    if (base && hasBlockRole(base)) {
+        const r = resolveRoleBlock(base, 'lease_up_schedule');
+        if (r.state === 'unresolvable') {
+            noteUnresolvable(ledger, 'lease_up_schedule', r.variants, 'CC-15', r.detail);
+            markSkipped(ledger, 'CC-15', 'variant_unresolvable', 'lease_up_schedule');
+            return;
+        }
+        ledger.resolutions['CC-15'] ??= {};
+        ledger.resolutions['CC-15']['lease_up_schedule'] = {
+            ...(base.annotation.variant ? { variant: base.annotation.variant } : {}), via: 'preference',
+        };
+    }
+    if (!base) {
         markSkipped(ledger, 'CC-15', 'not_applicable', 'no base variant');
+        return;
+    }
     const stabilizedNoi = base
         ? deepGet(base.content, 'stabilized_summary.annualized_noi')
         : undefined;
-    const noiModel = getSection(parsed, 'noi_model');
+    const noiModel = roleAwareDirectRead(parsed, 'noi_model', 'CC-15', ledger);
+    if (ledger.coverage['CC-15']?.reason === 'variant_unresolvable')
+        return;
     const modelNoi = deepGet(noiModel?.content, 'net_operating_income');
     if (base && !noiModel)
         markSkipped(ledger, 'CC-15', 'section_absent', 'noi_model');