@uwmd/core 1.1.0

package/dist/context.d.ts

@@ -0,0 +1,55 @@
+import type { ParsedUWFile, UWFrontmatter, PipelineStatus } from './types.js';
+import { type ContextProfile, type ContextResult } from './context-profiles.js';
+export interface LayerDefinition {
+    id: string;
+    layer: number;
+    name: string;
+    reads: string[];
+    writes: string[];
+    pipelineStateKey: string;
+    /**
+     * Normative context profile this layer consumes (Protocol §XI).
+     * Conformance Tier-4 verifies a host requests exactly this profile when
+     * preparing the layer's input. Phase 4 default; Phase 5 layers (L0a/L0b)
+     * declare their own.
+     */
+    consumed_profile: ContextProfile;
+}
+export declare const BANCROFT_LAYERS: LayerDefinition[];
+export interface AgentContext {
+    agentId: string;
+    layer: LayerDefinition;
+    frontmatter: UWFrontmatter;
+    sections: Record<string, unknown>;
+    prose: Record<string, string>;
+    missingRequired: string[];
+    missingOptional: string[];
+    customCalculations: unknown[];
+    customScenarios: unknown[];
+    extensions: Record<string, unknown>;
+    flags: string[];
+    blockingFlags: string[];
+    validationIssues?: unknown[];
+    pipelineState: Record<string, PipelineStatus>;
+    chatContext: string;
+    chatTokenEstimate: number;
+    /**
+     * Normative context payload built from the layer's `consumed_profile`
+     * (Protocol §XI). Hosts SHOULD send this — not `chatContext` — to the
+     * agent when running under the conformance contract.
+     */
+    profileContext: ContextResult;
+}
+export declare function buildAgentContext(parsed: ParsedUWFile, agentId: string, opts?: {
+    includeValidation?: boolean;
+    maxChatTokens?: number;
+}): AgentContext;
+export interface BancroftPrompt {
+    systemPrompt: string;
+    userMessage: string;
+    outputSchemaDescription: string;
+}
+export declare function buildAgentPrompt(context: AgentContext, userInstructions?: string): BancroftPrompt;
+export declare function isContextReady(context: AgentContext): boolean;
+export declare function getLayerDependencies(layerId: string): string[];
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAW,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGvF,OAAO,EAAgB,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI9F,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,EAAE,cAAc,CAAC;CAClC;AAED,eAAO,MAAM,eAAe,EAAE,eAAe,EAkF5C,CAAC;AAIF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,WAAW,EAAE,aAAa,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,OAAO,EAAE,CAAC;IAC9B,eAAe,EAAE,OAAO,EAAE,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE9C,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC;CAC/B;AAID,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,YAAY,CA2Ed;AAMD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,YAAY,EACrB,gBAAgB,CAAC,EAAE,MAAM,GACxB,cAAc,CAsChB;AAuED,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAM7D;AAKD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAa9D"}

package/dist/context.js

@@ -0,0 +1,288 @@
+// .uw.md context builder — curates what each Bancroft agent layer receives
+//
+// Each Bancroft layer has a defined set of sections it reads and writes.
+// This module builds the minimal, focused context an agent needs — not the
+// full file. Prevents agents from having to parse the raw .uw.md themselves,
+// and ensures each layer only sees the sections it depends on.
+//
+// Spec: UW_FORMAT_SPEC_v1.md §1.3 (Bancroft layer ↔ section mapping)
+import { getSection } from './parser.js';
+import { render } from './renderer.js';
+import { buildContext } from './context-profiles.js';
+export const BANCROFT_LAYERS = [
+    {
+        id: 'L0',
+        layer: 0,
+        name: 'Document Ingestion',
+        reads: [], // L0 reads raw documents, not sections
+        writes: ['rent_roll', 'operating_statement', 'lease_schedule'],
+        pipelineStateKey: 'L0_ingestion',
+        consumed_profile: 'summary',
+    },
+    {
+        id: 'L0a',
+        layer: 0,
+        name: 'Scope',
+        reads: ['property'],
+        writes: ['market_analysis', 'noi_model', 'debt_structure', 'valuation', 'quick_metrics', 'gaps'],
+        pipelineStateKey: 'L0a_scope',
+        consumed_profile: 'summary',
+    },
+    {
+        id: 'L0b',
+        layer: 0,
+        name: 'Scope Refinement',
+        reads: ['*'],
+        writes: ['property', 'noi_model', 'debt_structure', 'gaps'],
+        pipelineStateKey: 'L0b_refinement',
+        consumed_profile: 'compact',
+    },
+    {
+        id: 'L1',
+        layer: 1,
+        name: 'Screening',
+        reads: ['deal_context', 'property', 'ownership'],
+        writes: ['screening', 'preliminary_sizing'],
+        pipelineStateKey: 'L1_screening',
+        consumed_profile: 'summary',
+    },
+    {
+        id: 'L2',
+        layer: 2,
+        name: 'Underwriting',
+        reads: ['deal_context', 'property', 'rent_roll', 'operating_statement', 'borrower_sponsor'],
+        writes: ['noi_model', 'valuation', 'market_analysis'],
+        pipelineStateKey: 'L2_underwriting',
+        consumed_profile: 'relevant',
+    },
+    {
+        id: 'L4',
+        layer: 4,
+        name: 'Structuring',
+        reads: ['deal_context', 'property', 'noi_model', 'valuation', 'market_analysis', 'borrower_sponsor', 'sources_uses'],
+        writes: ['debt_structure', 'sources_uses', 'covenants'],
+        pipelineStateKey: 'L4_structuring',
+        consumed_profile: 'relevant',
+    },
+    {
+        id: 'L5',
+        layer: 5,
+        name: 'Compliance',
+        reads: ['deal_context', 'property', 'ownership', 'borrower_sponsor', 'debt_structure', 'valuation'],
+        writes: ['compliance'],
+        pipelineStateKey: 'L5_compliance',
+        consumed_profile: 'relevant',
+    },
+    {
+        id: 'L6',
+        layer: 6,
+        name: 'Risk Rating',
+        reads: ['deal_context', 'property', 'noi_model', 'valuation', 'debt_structure', 'market_analysis', 'borrower_sponsor', 'stress_tests', 'dcf', 'compliance'],
+        writes: ['risk_assessment'],
+        pipelineStateKey: 'L6_risk',
+        consumed_profile: 'relevant',
+    },
+    {
+        id: 'L7',
+        layer: 7,
+        name: 'Assembly',
+        reads: ['*'], // reads everything
+        writes: ['pipeline_log', 'deal_context'], // writes ai_synthesis to deal_context
+        pipelineStateKey: 'L7_assembly',
+        consumed_profile: 'live',
+    },
+];
+// ─── Main context builder ─────────────────────────────────────────────────────
+export function buildAgentContext(parsed, agentId, opts = {}) {
+    const layer = resolveLayer(agentId);
+    const sectionsToRead = layer.layer === 7 ? getAllSectionIds(parsed) : layer.reads;
+    // Collect section content
+    const sections = {};
+    const prose = {};
+    const missingRequired = [];
+    const missingOptional = [];
+    for (const sectionId of sectionsToRead) {
+        const block = getSection(parsed, sectionId);
+        if (block) {
+            sections[sectionId] = block.content;
+            if (parsed.prose[sectionId])
+                prose[sectionId] = parsed.prose[sectionId];
+        }
+        else {
+            // Check multi-variant
+            const variantEntry = parsed.sections[sectionId];
+            if (variantEntry && !('annotation' in variantEntry)) {
+                sections[sectionId] = Object.fromEntries(Object.entries(variantEntry).map(([v, b]) => [v, b.content]));
+            }
+            else if (isRequired(layer, sectionId)) {
+                missingRequired.push(sectionId);
+            }
+            else {
+                missingOptional.push(sectionId);
+            }
+        }
+    }
+    // Always include deal_context for all layers (orientation)
+    if (!sections['deal_context']) {
+        const dc = getSection(parsed, 'deal_context');
+        if (dc) {
+            sections['deal_context'] = dc.content;
+            if (parsed.prose['deal_context'])
+                prose['deal_context'] = parsed.prose['deal_context'];
+        }
+    }
+    const pipelineState = (parsed.frontmatter.pipeline_state ?? {});
+    // Build chat context string for Claude API injection
+    const chatResult = render(parsed, {
+        format: 'chat',
+        maxTokens: opts.maxChatTokens ?? 8000,
+    });
+    // Build the normative profile context per the layer's declared consumption.
+    // For 'relevant', pass layer.reads as the section filter so the host receives
+    // exactly the documented contract.
+    const profileContext = buildContext(parsed, layer.consumed_profile, {
+        sections: layer.consumed_profile === 'relevant' ? sectionsToRead : undefined,
+        maxTokens: opts.maxChatTokens,
+    });
+    return {
+        agentId,
+        layer,
+        frontmatter: parsed.frontmatter,
+        sections,
+        prose,
+        missingRequired,
+        missingOptional,
+        customCalculations: parsed.custom_calculations.map(b => b.content),
+        customScenarios: parsed.custom_scenarios.map(b => b.content),
+        extensions: Object.fromEntries(Object.entries(parsed.extensions).map(([k, v]) => [k, v.content])),
+        flags: parsed.frontmatter.flags ?? [],
+        blockingFlags: parsed.frontmatter.blocking_flags ?? [],
+        pipelineState,
+        chatContext: chatResult.content,
+        chatTokenEstimate: chatResult.estimatedTokens ?? 0,
+        profileContext,
+    };
+}
+export function buildAgentPrompt(context, userInstructions) {
+    const layer = context.layer;
+    const missingWarn = context.missingRequired.length > 0
+        ? `\n\n⚠ MISSING REQUIRED INPUT SECTIONS: ${context.missingRequired.join(', ')}. Proceed with available data only — mark confidence as "low" and set human_review_required: true for fields that depend on missing inputs.`
+        : '';
+    const systemPrompt = `You are ${layer.id} — ${layer.name} — a specialized agent in the Bancroft CRE underwriting pipeline.
+
+Your role: ${getLayerDescription(layer.id)}
+
+## Your Output Contract
+
+You must return a single JSON object that will be written as a .uw.md section block. The object must:
+- Begin with a "_meta" object (see spec §2.5)
+- Include all required fields for the section(s) you write: ${layer.writes.join(', ')}
+- Set confidence to "high" / "medium" / "low" based on available data quality
+- Set human_review_required: true if any field is uncertain, estimated, or depends on missing inputs
+- Never calculate financial figures — report what the data shows; the deterministic engine owns the math
+- Set flags[] for any anomalies, policy concerns, or data quality issues you observe
+
+## Available Input Sections
+${Object.keys(context.sections).map(s => `- ${s}`).join('\n')}
+${missingWarn}
+
+## Blocking Flags
+${context.blockingFlags.length > 0 ? context.blockingFlags.map(f => `- ${f}`).join('\n') : 'None — pipeline is clear to proceed'}`;
+    const userMessage = `${context.chatContext}
+
+---
+
+${userInstructions ? `Additional instructions:\n${userInstructions}\n\n---\n\n` : ''}Return your output as a single JSON block for section(s): ${layer.writes.join(', ')}`;
+    return {
+        systemPrompt,
+        userMessage,
+        outputSchemaDescription: getOutputSchemaDescription(layer.id),
+    };
+}
+// ─── Layer resolution ─────────────────────────────────────────────────────────
+function resolveLayer(agentId) {
+    // Match by prefix: "L0", "L0-01", "L2-CRE-11", etc.
+    const prefix = agentId.match(/^(L\d+)/)?.[1];
+    if (prefix) {
+        const layer = BANCROFT_LAYERS.find(l => l.id === prefix);
+        if (layer)
+            return layer;
+    }
+    // Default: treat as L7 (reads everything)
+    return BANCROFT_LAYERS[BANCROFT_LAYERS.length - 1];
+}
+// Sections that must be present for each layer to produce meaningful output.
+// Absent required sections set context.missingRequired and block isContextReady().
+const REQUIRED_BY_LAYER = {
+    L0: [],
+    L0a: ['property'],
+    L0b: [], // operates on whatever L0a produced
+    L1: ['property'],
+    L2: ['property', 'rent_roll'],
+    L4: ['noi_model', 'valuation'],
+    L5: ['property', 'borrower_sponsor'],
+    L6: ['noi_model', 'debt_structure', 'valuation'],
+    L7: [], // L7 reads everything but can always proceed
+};
+function isRequired(layer, sectionId) {
+    const required = REQUIRED_BY_LAYER[layer.id] ?? [];
+    return required.includes(sectionId);
+}
+function getAllSectionIds(parsed) {
+    return Object.keys(parsed.sections);
+}
+// ─── Layer descriptions ───────────────────────────────────────────────────────
+function getLayerDescription(layerId) {
+    const descriptions = {
+        L0: 'You extract structured data from raw uploaded documents (rent rolls, T-12 operating statements, lease schedules). Output must represent exactly what the documents say — no inference, no interpolation.',
+        L0a: 'You produce an initial scoped .uw.md from minimal user input by walking the fallback cascade. Every defaulted value MUST be stamped provisional. Your output is a triage view, not a commitment.',
+        L0b: 'You iteratively ask the user the smallest set of questions that meaningfully tighten the deal\u2019s output ranges. Wraps refinement.ts in a conversational loop. See L0b-prompt.md for the full system prompt.',
+        L1: 'You perform initial deal screening — flag red flags, assess deal feasibility against standard thresholds, and produce a preliminary sizing. You are the gatekeeper before full underwriting begins.',
+        L2: 'You perform full underwriting analysis — NOI reconstruction, market positioning, valuation, and borrower assessment. You are the primary analytical layer.',
+        L4: 'You structure the debt — size the loan, build the sources and uses table, design term sheet terms, and identify covenants. You work from the underwritten NOI and value.',
+        L5: 'You run compliance checks — OFAC screening, CRA assessment, regulatory requirements, and policy flag review. You are a hard gate: blocking flags must be cleared before proceeding.',
+        L6: 'You produce the risk rating — aggregate all section inputs into a scored assessment, stress test the structure, and make a recommendation.',
+        L7: 'You assemble the final package — synthesize all sections into a coherent narrative, generate the AI synthesis for deal_context, and prepare output artifacts.',
+    };
+    return descriptions[layerId] ?? 'You are a specialized underwriting agent.';
+}
+function getOutputSchemaDescription(layerId) {
+    const schemas = {
+        L0: 'rent_roll: { units[], gross_potential_rent, total_units } | operating_statement: { income{}, expenses{}, noi } | lease_schedule: { leases[] }',
+        L1: 'screening: { status, flags[], notes, recommendation } | preliminary_sizing: { max_loan_amount, dscr_estimate, ltv_estimate }',
+        L2: 'noi_model: { line_items{}, noi, vacancy_rate, opex_ratio } | valuation: { purchase_price, cap_rate, value_per_unit } | market_analysis: { market_vacancy, asking_rents, supply_pipeline }',
+        L4: 'debt_structure: { loan_amount, rate, term, ltv, dscr } | sources_uses: { sources{}, uses{}, equity_required }',
+        L5: 'compliance: { ofac_status, cra_eligible, flags[], blocking_flags[], notes }',
+        L6: 'risk_assessment: { overall_rating, risk_score, key_risks[], recommendation, stress_test_summary }',
+        L7: 'deal_context (ai_synthesis field): { summary, key_risks[], key_strengths[], overall_impression }',
+    };
+    return schemas[layerId] ?? '{ _meta: {}, ...section fields }';
+}
+// ─── Context readiness check ──────────────────────────────────────────────────
+// Returns true if the context has enough data to run the agent.
+export function isContextReady(context) {
+    // Blocking flags always halt
+    if (context.blockingFlags.length > 0)
+        return false;
+    // Missing required sections halt
+    if (context.missingRequired.length > 0)
+        return false;
+    return true;
+}
+// ─── Pipeline dependency graph ────────────────────────────────────────────────
+// Returns the layers that must complete before a given layer can run.
+export function getLayerDependencies(layerId) {
+    const deps = {
+        L0: [],
+        L0a: [],
+        L0b: ['L0a'],
+        L1: ['L0'],
+        L2: ['L0', 'L1'],
+        L4: ['L2'],
+        L5: ['L2', 'L4'],
+        L6: ['L2', 'L4', 'L5'],
+        L7: ['L0', 'L1', 'L2', 'L4', 'L5', 'L6'],
+    };
+    return deps[layerId] ?? [];
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,6EAA6E;AAC7E,+DAA+D;AAC/D,EAAE;AACF,qEAAqE;AAGrE,OAAO,EAAE,UAAU,EAA8B,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,YAAY,EAA2C,MAAM,uBAAuB,CAAC;AAoB9F,MAAM,CAAC,MAAM,eAAe,GAAsB;IAChD;QACE,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,EAAE,EAAG,uCAAuC;QACnD,MAAM,EAAE,CAAC,WAAW,EAAE,qBAAqB,EAAE,gBAAgB,CAAC;QAC9D,gBAAgB,EAAE,cAAc;QAChC,gBAAgB,EAAE,SAAS;KAC5B;IACD;QACE,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,CAAC,UAAU,CAAC;QACnB,MAAM,EAAE,CAAC,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,CAAC;QAChG,gBAAgB,EAAE,WAAW;QAC7B,gBAAgB,EAAE,SAAS;KAC5B;IACD;QACE,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,CAAC,GAAG,CAAC;QACZ,MAAM,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,CAAC;QAC3D,gBAAgB,EAAE,gBAAgB;QAClC,gBAAgB,EAAE,SAAS;KAC5B;IACD;QACE,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,CAAC,cAAc,EAAE,UAAU,EAAE,WAAW,CAAC;QAChD,MAAM,EAAE,CAAC,WAAW,EAAE,oBAAoB,CAAC;QAC3C,gBAAgB,EAAE,cAAc;QAChC,gBAAgB,EAAE,SAAS;KAC5B;IACD;QACE,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,CAAC,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,qBAAqB,EAAE,kBAAkB,CAAC;QAC3F,MAAM,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,iBAAiB,CAAC;QACrD,gBAAgB,EAAE,iBAAiB;QACnC,gBAAgB,EAAE,UAAU;KAC7B;IACD;QACE,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,CAAC,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,cAAc,CAAC;QACpH,MAAM,EAAE,CAAC,gBAAgB,EAAE,cAAc,EAAE,WAAW,CAAC;QACvD,gBAAgB,EAAE,gBAAgB;QAClC,gBAAgB,EAAE,UAAU;KAC7B;IACD;QACE,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,CAAC,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,CAAC;QACnG,MAAM,EAAE,CAAC,YAAY,CAAC;QACtB,gBAAgB,EAAE,eAAe;QACjC,gBAAgB,EAAE,UAAU;KAC7B;IACD;QACE,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,CAAC,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,CAAC;QAC3J,MAAM,EAAE,CAAC,iBAAiB,CAAC;QAC3B,gBAAgB,EAAE,SAAS;QAC3B,gBAAgB,EAAE,UAAU;KAC7B;IACD;QACE,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,CAAC,GAAG,CAAC,EAAG,mBAAmB;QAClC,MAAM,EAAE,CAAC,cAAc,EAAE,cAAc,CAAC,EAAG,sCAAsC;QACjF,gBAAgB,EAAE,aAAa;QAC/B,gBAAgB,EAAE,MAAM;KACzB;CACF,CAAC;AA8BF,iFAAiF;AAEjF,MAAM,UAAU,iBAAiB,CAC/B,MAAoB,EACpB,OAAe,EACf,OAAgE,EAAE;IAElE,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;IAElF,0BAA0B;IAC1B,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,MAAM,eAAe,GAAa,EAAE,CAAC;IACrC,MAAM,eAAe,GAAa,EAAE,CAAC;IAErC,KAAK,MAAM,SAAS,IAAI,cAAc,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC5C,IAAI,KAAK,EAAE,CAAC;YACV,QAAQ,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;YACpC,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC;gBAAE,KAAK,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC1E,CAAC;aAAM,CAAC;YACN,sBAAsB;YACtB,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YAChD,IAAI,YAAY,IAAI,CAAC,CAAC,YAAY,IAAI,YAAY,CAAC,EAAE,CAAC;gBACpD,QAAQ,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,YAAuC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CACxF,CAAC;YACJ,CAAC;iBAAM,IAAI,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;gBACxC,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED,2DAA2D;IAC3D,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QAC9C,IAAI,EAAE,EAAE,CAAC;YACP,QAAQ,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;YACtC,IAAI,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC;gBAAE,KAAK,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,cAAc,IAAI,EAAE,CAAmC,CAAC;IAElG,qDAAqD;IACrD,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE;QAChC,MAAM,EAAE,MAAM;QACd,SAAS,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI;KACtC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,8EAA8E;IAC9E,mCAAmC;IACnC,MAAM,cAAc,GAAG,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,gBAAgB,EAAE;QAClE,QAAQ,EAAE,KAAK,CAAC,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS;QAC5E,SAAS,EAAE,IAAI,CAAC,aAAa;KAC9B,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;QACP,KAAK;QACL,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ;QACR,KAAK;QACL,eAAe;QACf,eAAe;QACf,kBAAkB,EAAE,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAClE,eAAe,EAAE,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAC5D,UAAU,EAAE,MAAM,CAAC,WAAW,CAC5B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAClE;QACD,KAAK,EAAG,MAAM,CAAC,WAAW,CAAC,KAA8B,IAAI,EAAE;QAC/D,aAAa,EAAG,MAAM,CAAC,WAAW,CAAC,cAAuC,IAAI,EAAE;QAChF,aAAa;QACb,WAAW,EAAE,UAAU,CAAC,OAAO;QAC/B,iBAAiB,EAAE,UAAU,CAAC,eAAe,IAAI,CAAC;QAClD,cAAc;KACf,CAAC;AACJ,CAAC;AAYD,MAAM,UAAU,gBAAgB,CAC9B,OAAqB,EACrB,gBAAyB;IAEzB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,MAAM,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QACpD,CAAC,CAAC,0CAA0C,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,6IAA6I;QAC3N,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,YAAY,GAAG,WAAW,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC,IAAI;;aAE7C,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;;;;;;8DAMoB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;EAOnF,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;EAC3D,WAAW;;;EAGX,OAAO,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,qCAAqC,EAAE,CAAC;IAEjI,MAAM,WAAW,GAAG,GAAG,OAAO,CAAC,WAAW;;;;EAI1C,gBAAgB,CAAC,CAAC,CAAC,6BAA6B,gBAAgB,aAAa,CAAC,CAAC,CAAC,EAAE,6DAA6D,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAEzK,OAAO;QACL,YAAY;QACZ,WAAW;QACX,uBAAuB,EAAE,0BAA0B,CAAC,KAAK,CAAC,EAAE,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF,SAAS,YAAY,CAAC,OAAe;IACnC,oDAAoD;IACpD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7C,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACzD,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,0CAA0C;IAC1C,OAAO,eAAe,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,6EAA6E;AAC7E,mFAAmF;AACnF,MAAM,iBAAiB,GAA6B;IAClD,EAAE,EAAE,EAAE;IACN,GAAG,EAAE,CAAC,UAAU,CAAC;IACjB,GAAG,EAAE,EAAE,EAAI,oCAAoC;IAC/C,EAAE,EAAE,CAAC,UAAU,CAAC;IAChB,EAAE,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;IAC7B,EAAE,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC;IAC9B,EAAE,EAAE,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACpC,EAAE,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,WAAW,CAAC;IAChD,EAAE,EAAE,EAAE,EAAG,6CAA6C;CACvD,CAAC;AAEF,SAAS,UAAU,CAAC,KAAsB,EAAE,SAAiB;IAC3D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;IACnD,OAAO,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAoB;IAC5C,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED,iFAAiF;AAEjF,SAAS,mBAAmB,CAAC,OAAe;IAC1C,MAAM,YAAY,GAA2B;QAC3C,EAAE,EAAE,0MAA0M;QAC9M,GAAG,EAAE,kMAAkM;QACvM,GAAG,EAAE,iNAAiN;QACtN,EAAE,EAAE,qMAAqM;QACzM,EAAE,EAAE,4JAA4J;QAChK,EAAE,EAAE,0KAA0K;QAC9K,EAAE,EAAE,qLAAqL;QACzL,EAAE,EAAE,4IAA4I;QAChJ,EAAE,EAAE,+JAA+J;KACpK,CAAC;IACF,OAAO,YAAY,CAAC,OAAO,CAAC,IAAI,2CAA2C,CAAC;AAC9E,CAAC;AAED,SAAS,0BAA0B,CAAC,OAAe;IACjD,MAAM,OAAO,GAA2B;QACtC,EAAE,EAAE,+IAA+I;QACnJ,EAAE,EAAE,8HAA8H;QAClI,EAAE,EAAE,2LAA2L;QAC/L,EAAE,EAAE,+GAA+G;QACnH,EAAE,EAAE,6EAA6E;QACjF,EAAE,EAAE,mGAAmG;QACvG,EAAE,EAAE,kGAAkG;KACvG,CAAC;IACF,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,kCAAkC,CAAC;AAChE,CAAC;AAED,iFAAiF;AACjF,gEAAgE;AAEhE,MAAM,UAAU,cAAc,CAAC,OAAqB;IAClD,6BAA6B;IAC7B,IAAI,OAAO,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACnD,iCAAiC;IACjC,IAAI,OAAO,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iFAAiF;AACjF,sEAAsE;AAEtE,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,MAAM,IAAI,GAA6B;QACrC,EAAE,EAAE,EAAE;QACN,GAAG,EAAE,EAAE;QACP,GAAG,EAAE,CAAC,KAAK,CAAC;QACZ,EAAE,EAAE,CAAC,IAAI,CAAC;QACV,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;QAChB,EAAE,EAAE,CAAC,IAAI,CAAC;QACV,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;QAChB,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;QACtB,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC;KACzC,CAAC;IACF,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;AAC7B,CAAC"}

package/dist/dcf.d.ts

@@ -0,0 +1,9 @@
+import { type DerivedField } from './derived.js';
+type Row = Record<string, unknown>;
+export interface DCFDerivation {
+    fields: DerivedField[];
+}
+/** Foot a dcf content block. Pure: never mutates `content`. */
+export declare function deriveDCF(content: Row): DCFDerivation;
+export {};
+//# sourceMappingURL=dcf.d.ts.map

package/dist/dcf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dcf.d.ts","sourceRoot":"","sources":["../src/dcf.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEvE,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAKnC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,aAAa,CA+DrD"}

package/dist/dcf.js

@@ -0,0 +1,75 @@
+// Deterministic DCF footing — the relationships inside a `dcf` block that follow
+// unambiguously from the block's own stored inputs are footed here, so the editor,
+// CLI, and Excel converter never disagree (invariant #4); plain arithmetic, never
+// AI math (invariant #1).
+//
+// Scope is deliberately narrow and self-contained, in the same spirit as
+// deriveValuation. We foot only what is an identity over stored fields:
+//
+//   Per projection year (annual_cash_flows[i]):
+//     net_cash_flow_levered = net_operating_income − annual_debt_service
+//     cash_on_cash_return   = net_cash_flow_levered / cumulative_equity_invested
+//
+//   Exit waterfall (exit_analysis):
+//     disposition_costs       = exit_value_gross × assumptions.disposition_costs_pct
+//     exit_value_net          = exit_value_gross − disposition_costs
+//     net_proceeds_to_equity  = exit_value_net − loan_balance_at_exit
+//
+// Left as INPUTS on purpose (no unambiguous identity from stored fields):
+//   - exit_value_gross — capitalizes a *forward* NOI by convention (year N+1),
+//     which the block doesn't store; the trailing exit_noi alone can't foot it.
+//   - returns.* (IRR / NPV / equity multiple) — depend on a cash-flow timing /
+//     terminal-value convention; computing them here would invite silent drift.
+//   - per-unit / per-sqft exit values — need the property section.
+import { collector, numOrNull } from './derived.js';
+const num = numOrNull;
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** Foot a dcf content block. Pure: never mutates `content`. */
+export function deriveDCF(content) {
+    const c = collector();
+    // ─── Per-year levered cash flow + cash-on-cash ──────────────────────────────
+    const flows = content['annual_cash_flows'];
+    if (Array.isArray(flows)) {
+        flows.forEach((row, i) => {
+            if (!isObj(row))
+                return;
+            const noi = num(row['net_operating_income']);
+            const ads = num(row['annual_debt_service']);
+            if (noi == null || ads == null)
+                return;
+            const levered = noi - ads;
+            c.add(`annual_cash_flows.${i}.net_cash_flow_levered`, `Year ${labelYear(row, i)} — Levered Cash Flow`, 'currency', levered);
+            const equity = num(row['cumulative_equity_invested']);
+            if (equity != null && equity > 0) {
+                c.add(`annual_cash_flows.${i}.cash_on_cash_return`, `Year ${labelYear(row, i)} — Cash-on-Cash`, 'rate', levered / equity);
+            }
+        });
+    }
+    // ─── Exit waterfall ─────────────────────────────────────────────────────────
+    const exit = isObj(content['exit_analysis']) ? content['exit_analysis'] : null;
+    const assumptions = isObj(content['assumptions']) ? content['assumptions'] : null;
+    if (exit) {
+        const gross = num(exit['exit_value_gross']);
+        const dispPct = assumptions ? num(assumptions['disposition_costs_pct']) : null;
+        let dispCosts = num(exit['disposition_costs']);
+        if (gross != null && dispPct != null) {
+            dispCosts = Math.round(gross * dispPct);
+            c.add('exit_analysis.disposition_costs', 'Disposition Costs', 'currency', dispCosts);
+        }
+        let net = num(exit['exit_value_net']);
+        if (gross != null && dispCosts != null) {
+            net = gross - dispCosts;
+            c.add('exit_analysis.exit_value_net', 'Exit Value (net of costs)', 'currency', net);
+        }
+        const loanAtExit = num(exit['loan_balance_at_exit']);
+        if (net != null && loanAtExit != null) {
+            c.add('exit_analysis.net_proceeds_to_equity', 'Net Sale Proceeds to Equity', 'currency', net - loanAtExit);
+        }
+    }
+    return { fields: c.fields };
+}
+function labelYear(row, i) {
+    const y = num(row['year']);
+    return y ?? i + 1;
+}
+//# sourceMappingURL=dcf.js.map

package/dist/dcf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dcf.js","sourceRoot":"","sources":["../src/dcf.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,mFAAmF;AACnF,kFAAkF;AAClF,0BAA0B;AAC1B,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,EAAE;AACF,gDAAgD;AAChD,yEAAyE;AACzE,iFAAiF;AACjF,EAAE;AACF,oCAAoC;AACpC,qFAAqF;AACrF,qEAAqE;AACrE,sEAAsE;AACtE,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,gFAAgF;AAChF,mEAAmE;AAEnE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAqB,MAAM,cAAc,CAAC;AAIvE,MAAM,GAAG,GAAG,SAAS,CAAC;AACtB,MAAM,KAAK,GAAG,CAAC,CAAU,EAAY,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAMjG,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,OAAY;IACpC,MAAM,CAAC,GAAG,SAAS,EAAE,CAAC;IAEtB,+EAA+E;IAC/E,MAAM,KAAK,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;YACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;gBAAE,OAAO;YACxB,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC;YAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC;YAC5C,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,IAAI,IAAI;gBAAE,OAAO;YAEvC,MAAM,OAAO,GAAG,GAAG,GAAG,GAAG,CAAC;YAC1B,CAAC,CAAC,GAAG,CACH,qBAAqB,CAAC,wBAAwB,EAC9C,QAAQ,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,sBAAsB,EAC/C,UAAU,EACV,OAAO,CACR,CAAC;YAEF,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,CAAC;YACtD,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjC,CAAC,CAAC,GAAG,CACH,qBAAqB,CAAC,sBAAsB,EAC5C,QAAQ,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,iBAAiB,EAC1C,MAAM,EACN,OAAO,GAAG,MAAM,CACjB,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,+EAA+E;IAC/E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/E,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAE/E,IAAI,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;QAC/C,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;YACrC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC,CAAC;YACxC,CAAC,CAAC,GAAG,CAAC,iCAAiC,EAAE,mBAAmB,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;QACvF,CAAC;QAED,IAAI,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;QACtC,IAAI,KAAK,IAAI,IAAI,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;YACvC,GAAG,GAAG,KAAK,GAAG,SAAS,CAAC;YACxB,CAAC,CAAC,GAAG,CAAC,8BAA8B,EAAE,2BAA2B,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QACtF,CAAC;QAED,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC;QACrD,IAAI,GAAG,IAAI,IAAI,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;YACtC,CAAC,CAAC,GAAG,CACH,sCAAsC,EACtC,6BAA6B,EAC7B,UAAU,EACV,GAAG,GAAG,UAAU,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,SAAS,CAAC,GAAQ,EAAE,CAAS;IACpC,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpB,CAAC"}

package/dist/debt.d.ts

@@ -0,0 +1,11 @@
+import { type DerivedField } from './derived.js';
+type Row = Record<string, unknown>;
+export interface DebtDerivation {
+    fields: DerivedField[];
+    /** True when the loan is interest-only (no amortizing payment). */
+    interestOnly: boolean;
+}
+/** Foot a debt_structure content block. Pure: never mutates `content`. */
+export declare function deriveDebt(content: Row): DebtDerivation;
+export {};
+//# sourceMappingURL=debt.d.ts.map

package/dist/debt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debt.d.ts","sourceRoot":"","sources":["../src/debt.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEvE,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAInC,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,mEAAmE;IACnE,YAAY,EAAE,OAAO,CAAC;CACvB;AAoCD,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,cAAc,CA6BvD"}

package/dist/debt.js

@@ -0,0 +1,85 @@
+// Deterministic debt-service footing — the loan terms (amount, rate, amortization,
+// IO) are the inputs; monthly and annual debt service foot from them. Same role
+// for the debt_structure section that deriveRentRoll / deriveOperatingStatement
+// play for their sections: one source of truth so the editor, CLI, and Excel
+// converter never disagree (invariant #4).
+//
+// This is plain deterministic arithmetic — the standard mortgage payment formula,
+// not AI math (invariant #1). The pmt() here is byte-identical to the calc
+// engine's `pmt` builtin (calc/builtins.ts) so a footed annual_debt_service equals
+// what `evaluateCalc` would produce from the same inputs.
+//
+// Conventions:
+//  - Amortizing loan: monthly_debt_service = pmt(rate/12, amort_years*12, loan);
+//    annual_debt_service = monthly * 12. This is the *fully-amortizing* payment —
+//    the conservative figure DSCR/debt-yield are sized against — even when the
+//    loan carries an initial interest-only period.
+//  - Interest-only loan: annual_debt_service = loan * rate; monthly = annual / 12.
+//  - Field-name tolerance: the rate is read from the first present of several
+//    conventions (interest_rate, all_in_rate_at_close, note_rate_at_close, …);
+//    IO is detected from amortization === "interest_only" or a missing/zero
+//    amortization term.
+import { collector, numOrNull } from './derived.js';
+const num = numOrNull;
+const RATE_KEYS = [
+    'interest_rate',
+    'all_in_rate_at_close',
+    'note_rate_at_close',
+    'interest_rate_at_close',
+];
+const AMORT_KEYS = ['amortization_years', 'amortization_period_years'];
+function firstNum(row, keys) {
+    for (const k of keys) {
+        const n = num(row[k]);
+        if (n != null)
+            return n;
+    }
+    return null;
+}
+/** Standard mortgage payment — positive periodic payment for present value `pv`
+ *  at periodic `rate` over `n` periods. Identical to calc/builtins.ts `pmt`. */
+function pmt(rate, n, pv) {
+    if (n === 0)
+        return 0;
+    if (rate === 0)
+        return pv / n;
+    return (pv * rate) / (1 - (1 + rate) ** -n);
+}
+/** Is this an interest-only loan (no amortizing payment)? */
+function isInterestOnly(content) {
+    const amortStr = content['amortization'];
+    if (typeof amortStr === 'string' && amortStr.toLowerCase().replace(/[\s-]/g, '_') === 'interest_only') {
+        return true;
+    }
+    const amortYears = firstNum(content, AMORT_KEYS);
+    return amortYears == null || amortYears <= 0;
+}
+/** Foot a debt_structure content block. Pure: never mutates `content`. */
+export function deriveDebt(content) {
+    const c = collector();
+    const loan = num(content['loan_amount']);
+    const rate = firstNum(content, RATE_KEYS);
+    const interestOnly = isInterestOnly(content);
+    if (loan == null || rate == null) {
+        return { fields: c.fields, interestOnly };
+    }
+    let monthly;
+    let annual;
+    if (interestOnly) {
+        // Interest-only: annual = loan × rate is the authoritative figure; monthly
+        // is just annual / 12 (rounded for whole-dollar display).
+        annual = loan * rate;
+        monthly = annual / 12;
+    }
+    else {
+        // Amortizing: files store a whole-dollar monthly payment with annual = 12 ×
+        // that, so the two always foot together; round monthly first.
+        const amortYears = firstNum(content, AMORT_KEYS) ?? 0;
+        monthly = Math.round(pmt(rate / 12, amortYears * 12, loan));
+        annual = monthly * 12;
+    }
+    c.add('monthly_debt_service', 'Monthly Debt Service', 'currency', monthly);
+    c.add('annual_debt_service', 'Annual Debt Service', 'currency', annual);
+    return { fields: c.fields, interestOnly };
+}
+//# sourceMappingURL=debt.js.map

package/dist/debt.js.map

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