@uwmd/core 1.10.0 → 2.1.0

package/dist/cash-flow-series.js

@@ -0,0 +1,298 @@
+// Cash-flow series — state-and-verify dated flows (RFC 0034, UW_FORMAT_SPEC §4.26).
+//
+// A deal states dated, irregular flows — ISO calendar dates, signed amounts —
+// and optionally the aggregates over them (total, MOIC, XNPV at a rate, XIRR).
+// This module carries the §VIII.9 procedures (xnpv closed-form; xirr by the
+// RFC 0024 bisection verbatim, over date-derived exponents) and recomputes
+// each stated metric to a three-state verdict, the same shape as
+// `verifyCapitalStack` and `verifyLeaseUpSchedule`.
+//
+// This deliberately does NOT touch the Tier-3 calc engine: the series is
+// stated data, not formulas, and neither xnpv nor xirr is reachable from a
+// §VIII.1 expression. Structural rules (date grammar, ordering, sign change)
+// are validator errors (`CF-01`…`CF-03`, validator.ts), not verifier findings
+// — structure is validation, arithmetic is verification. A structurally
+// broken series makes every stated metric `unverifiable` here, never a guess.
+// Browser-safe; performs no I/O.
+import { CalcError } from './calc/errors.js';
+import { DEFAULT_DAY_COUNT, isDayCountConvention, parseISODate, yearfrac, } from './calc/day-count.js';
+import { IRR_BRACKET_LO, IRR_BRACKET_HI, IRR_VALUE_TOL, IRR_INTERVAL_TOL, IRR_MAX_ITER, } from './calc/builtins.js';
+// ─── Types (§4.26) ───────────────────────────────────────────────────────────
+/** Advisory flow taxonomy. Closed; gates no rule (§4.26). */
+export const CASH_FLOW_KINDS = Object.freeze([
+    'acquisition',
+    'operating',
+    'capex',
+    'debt_service',
+    'refinance',
+    'disposition',
+    'other',
+]);
+// ─── Quantization ────────────────────────────────────────────────────────────
+/**
+ * The decimal quantum each metric family is compared at (protocol §VIII.5
+ * posture: both sides quantize at the same boundary; §VIII.9.4 unit defaults:
+ * `$` → 2, `%` → 6, `x` → 4). Exported so any emitting surface quantizes
+ * where this verifier does rather than keeping its own copy.
+ */
+export const CASH_FLOW_VERIFY_DECIMALS = Object.freeze({
+    currency: 2,
+    rate: 6,
+    ratio: 4,
+});
+function roundTo(value, decimals) {
+    // Half away from zero, the §VIII.5 rule — Math.round is half-up, which
+    // differs for negatives, and a series' net total is routinely negative.
+    const f = 10 ** decimals;
+    const scaled = value * f;
+    return (scaled < 0 ? -Math.round(-scaled) : Math.round(scaled)) / f;
+}
+function isNum(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+/**
+ * Reduce a structurally valid series to anchor-relative dated flows, or
+ * `null` when any row is outside the CF-01/CF-02 grammar — the caller
+ * decides whether that is a validator error, a verifier `unverifiable`,
+ * or a `CALC-CF-SERIES` refusal; this function never throws.
+ */
+export function datedFlowsOf(series) {
+    const rows = series.series;
+    if (!Array.isArray(rows) || rows.length === 0)
+        return null;
+    const convention = series.day_count ?? DEFAULT_DAY_COUNT;
+    if (!isDayCountConvention(convention))
+        return null;
+    const dates = [];
+    for (const row of rows) {
+        if (!row || typeof row.date !== 'string' || !isNum(row.amount))
+            return null;
+        const d = parseISODate(row.date);
+        if (d === null)
+            return null;
+        dates.push(d);
+    }
+    const anchor = dates[0];
+    const flows = [];
+    let prev = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < rows.length; i++) {
+        const t = yearfrac(anchor, dates[i], convention);
+        if (t < prev)
+            return null; // non-decreasing dates (CF-02)
+        prev = t;
+        flows.push({ t, amount: rows[i].amount });
+    }
+    return flows;
+}
+/**
+ * xnpv(r) over anchor-relative flows — protocol §VIII.9.2, closed-form,
+ * accumulated in series order. `r <= -1` raises CALC-TYPE-001.
+ */
+export function xnpvOf(flows, rate) {
+    if (!isNum(rate) || rate <= -1) {
+        throw new CalcError('CALC-TYPE-001', `xnpv: rate must be a finite fraction greater than -1, got ${String(rate)}.`);
+    }
+    let acc = 0;
+    for (const f of flows)
+        acc += f.amount * (1 + rate) ** -f.t;
+    return acc;
+}
+/**
+ * xirr over anchor-relative flows — protocol §VIII.9.3: the §VIII.3 `irr`
+ * procedure verbatim with `npv` replaced by `xnpv`. Same bracket, same
+ * tolerances, exact high-endpoint root, no Newton polish; failure raises
+ * `CALC-XIRR-DIVERGE`.
+ */
+export function xirrOf(flows) {
+    const f = (r) => {
+        let acc = 0;
+        for (const fl of flows)
+            acc += fl.amount * (1 + r) ** -fl.t;
+        return acc;
+    };
+    let lo = IRR_BRACKET_LO;
+    let hi = IRR_BRACKET_HI;
+    let flo = f(lo);
+    const fhi = f(hi);
+    if (!Number.isFinite(flo) || !Number.isFinite(fhi) || flo * fhi > 0) {
+        throw new CalcError('CALC-XIRR-DIVERGE', `xirr: no sign change over the [${IRR_BRACKET_LO}, ${IRR_BRACKET_HI}] bracket (-99.9% to 1000%), so no root is reported.`);
+    }
+    // Exact endpoint root — reachable at `hi`; see §VIII.3's low-endpoint note.
+    if (flo === 0)
+        return lo;
+    if (fhi === 0)
+        return hi;
+    for (let i = 0; i < IRR_MAX_ITER; i++) {
+        const mid = (lo + hi) / 2;
+        const fmid = f(mid);
+        if (Math.abs(fmid) < IRR_VALUE_TOL || (hi - lo) / 2 < IRR_INTERVAL_TOL)
+            return mid;
+        if (flo * fmid < 0) {
+            hi = mid;
+        }
+        else {
+            lo = mid;
+            flo = fmid;
+        }
+    }
+    throw new CalcError('CALC-XIRR-DIVERGE', `xirr: bisection did not meet a stopping condition within ${IRR_MAX_ITER} iterations.`);
+}
+// ─── Verification ────────────────────────────────────────────────────────────
+/**
+ * Recompute every stated metric and report a three-state verdict:
+ *   - a metric disagrees beyond its quantum, or the procedure refuses a
+ *     stated value outright → `failed`
+ *   - a metric cannot be recomputed from what is stated (structurally broken
+ *     series, MOIC with no outflows) → `unverifiable`
+ *   - otherwise → `verified`
+ *
+ * The closed recompute vocabulary (§4.26 / §VIII.9.4):
+ *   - `total_net` = Σ amount (currency quantum)
+ *   - `moic` = Σ inflows ÷ |Σ outflows| (ratio quantum; no outflows → unverifiable)
+ *   - `xnpv.value` = §VIII.9.2 at the stated rate (currency quantum)
+ *   - `xirr` = §VIII.9.3 (rate quantum; a procedure refusal is `failed` —
+ *     the document asserts a number the procedure cannot produce)
+ *
+ * A `verified` series means the stated metrics follow deterministically from
+ * the stated rows. It does not mean the projection is achievable.
+ */
+export function verifyCashFlowSeries(series) {
+    const issues = [];
+    const stated = series.stated_metrics;
+    if (!stated)
+        return { verdict: 'verified', issues };
+    const statedMetrics = ['total_net', 'moic', 'xnpv', 'xirr'].filter((m) => {
+        const v = stated[m];
+        return v !== undefined && v !== null;
+    });
+    if (statedMetrics.length === 0)
+        return { verdict: 'verified', issues };
+    const flows = datedFlowsOf(series);
+    if (flows === null) {
+        for (const metric of statedMetrics) {
+            issues.push({
+                code: 'CF-UNEVALUABLE',
+                severity: 'indeterminate',
+                metric,
+                message: `stated_metrics.${metric} is stated but the series is structurally invalid (CF-01/CF-02), so it cannot be verified.`,
+            });
+        }
+        return { verdict: 'unverifiable', issues };
+    }
+    if (isNum(stated.total_net)) {
+        const dp = CASH_FLOW_VERIFY_DECIMALS.currency;
+        const recomputed = roundTo(flows.reduce((acc, f) => acc + f.amount, 0), dp);
+        const claim = roundTo(stated.total_net, dp);
+        if (claim !== recomputed) {
+            issues.push({
+                code: 'CF-METRIC-DISAGREES',
+                severity: 'failure',
+                metric: 'total_net',
+                message: `stated_metrics.total_net states ${stated.total_net} but the series sums to ${recomputed}.`,
+                expected: String(claim),
+                actual: String(recomputed),
+            });
+        }
+    }
+    if (isNum(stated.moic)) {
+        let inflows = 0;
+        let outflows = 0;
+        for (const f of flows) {
+            if (f.amount >= 0)
+                inflows += f.amount;
+            else
+                outflows += -f.amount;
+        }
+        if (outflows === 0) {
+            issues.push({
+                code: 'CF-UNEVALUABLE',
+                severity: 'indeterminate',
+                metric: 'moic',
+                message: 'stated_metrics.moic is stated but the series has no outflows, so the multiple is undefined and cannot be verified.',
+            });
+        }
+        else {
+            const dp = CASH_FLOW_VERIFY_DECIMALS.ratio;
+            const recomputed = roundTo(inflows / outflows, dp);
+            const claim = roundTo(stated.moic, dp);
+            if (claim !== recomputed) {
+                issues.push({
+                    code: 'CF-METRIC-DISAGREES',
+                    severity: 'failure',
+                    metric: 'moic',
+                    message: `stated_metrics.moic states ${stated.moic} but the series recomputes to ${recomputed}.`,
+                    expected: String(claim),
+                    actual: String(recomputed),
+                });
+            }
+        }
+    }
+    const xnpvClaim = stated.xnpv;
+    if (xnpvClaim && isNum(xnpvClaim.rate) && isNum(xnpvClaim.value)) {
+        try {
+            const dp = CASH_FLOW_VERIFY_DECIMALS.currency;
+            const recomputed = roundTo(xnpvOf(flows, xnpvClaim.rate), dp);
+            const claim = roundTo(xnpvClaim.value, dp);
+            if (claim !== recomputed) {
+                issues.push({
+                    code: 'CF-METRIC-DISAGREES',
+                    severity: 'failure',
+                    metric: 'xnpv',
+                    message: `stated_metrics.xnpv.value states ${xnpvClaim.value} at rate ${xnpvClaim.rate} but §VIII.9.2 recomputes to ${recomputed}.`,
+                    expected: String(claim),
+                    actual: String(recomputed),
+                });
+            }
+        }
+        catch (e) {
+            issues.push({
+                code: 'CF-PROCEDURE-REFUSES',
+                severity: 'failure',
+                metric: 'xnpv',
+                message: `stated_metrics.xnpv states a value the §VIII.9.2 procedure refuses: ${e instanceof Error ? e.message : String(e)}`,
+            });
+        }
+    }
+    else if (xnpvClaim) {
+        issues.push({
+            code: 'CF-UNEVALUABLE',
+            severity: 'indeterminate',
+            metric: 'xnpv',
+            message: 'stated_metrics.xnpv must state both a finite rate and value to be verifiable.',
+        });
+    }
+    if (isNum(stated.xirr)) {
+        try {
+            const dp = CASH_FLOW_VERIFY_DECIMALS.rate;
+            const recomputed = roundTo(xirrOf(flows), dp);
+            const claim = roundTo(stated.xirr, dp);
+            if (claim !== recomputed) {
+                issues.push({
+                    code: 'CF-METRIC-DISAGREES',
+                    severity: 'failure',
+                    metric: 'xirr',
+                    message: `stated_metrics.xirr states ${stated.xirr} but §VIII.9.3 recomputes to ${recomputed}.`,
+                    expected: String(claim),
+                    actual: String(recomputed),
+                });
+            }
+        }
+        catch (e) {
+            // The document asserts a number the procedure cannot produce (§4.26).
+            issues.push({
+                code: 'CF-PROCEDURE-REFUSES',
+                severity: 'failure',
+                metric: 'xirr',
+                message: `stated_metrics.xirr states a value the §VIII.9.3 procedure refuses: ${e instanceof Error ? e.message : String(e)}`,
+            });
+        }
+    }
+    if (issues.some((i) => i.severity === 'failure')) {
+        return { verdict: 'failed', issues };
+    }
+    if (issues.some((i) => i.severity === 'indeterminate')) {
+        return { verdict: 'unverifiable', issues };
+    }
+    return { verdict: 'verified', issues };
+}
+//# sourceMappingURL=cash-flow-series.js.map

package/dist/cash-flow-series.js.map

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

package/dist/cli-portfolio.d.ts

@@ -0,0 +1,7 @@
+type Flags = Record<string, string | boolean>;
+/** `uwmd portfolio validate <sidecar.uwportfolio.json> [--json]` */
+export declare function cmdPortfolioValidate(path: string, flags: Flags): void;
+/** `uwmd portfolio edges <sidecar.uwportfolio.json> [--entity <id>] [--json]` */
+export declare function cmdPortfolioEdges(path: string, flags: Flags): void;
+export {};
+//# sourceMappingURL=cli-portfolio.d.ts.map

package/dist/cli-portfolio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-portfolio.d.ts","sourceRoot":"","sources":["../src/cli-portfolio.ts"],"names":[],"mappings":"AAgBA,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAY9C,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAyBrE;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAkBlE"}

package/dist/cli-portfolio.js

@@ -0,0 +1,68 @@
+// CLI commands for RFC 0015: portfolio & relationship profile sidecars.
+//
+// Node-side commands reached only through the CLI entry point, never from
+// browser.ts. Split from cli-packages.ts because that file is the RFC 0018
+// surface and this is a different RFC's; both follow the same conventions.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { validatePortfolioProfile, uninterpretedPortfolioTypes, getPortfolioRelationships, } from './portfolio.js';
+function readJSONFile(path) {
+    return JSON.parse(readFileSync(resolve(path), 'utf-8'));
+}
+function printErrors(errors) {
+    for (const e of errors) {
+        console.log(`  ${e.code}${e.pointer ? ` [${e.pointer}]` : ''} ${e.message}`);
+    }
+}
+/** `uwmd portfolio validate <sidecar.uwportfolio.json> [--json]` */
+export function cmdPortfolioValidate(path, flags) {
+    const candidate = readJSONFile(path);
+    const errors = validatePortfolioProfile(candidate);
+    const uninterpreted = errors.length === 0
+        ? uninterpretedPortfolioTypes(candidate)
+        : { entity_types: [], edge_types: [] };
+    if (flags['json']) {
+        console.log(JSON.stringify({ ok: errors.length === 0, errors, uninterpreted }, null, 2));
+    }
+    else if (errors.length === 0) {
+        const profile = candidate;
+        console.log(`OK — ${profile.entities.length} entities, ${profile.edges.length} edges.`);
+        for (const [label, types] of [
+            ['entity', uninterpreted.entity_types],
+            ['edge', uninterpreted.edge_types],
+        ]) {
+            if (types.length > 0) {
+                console.log(`  note: uninterpreted ${label} type(s) preserved: ${types.join(', ')}`);
+            }
+        }
+    }
+    else {
+        console.log(`INVALID — ${errors.length} error(s):`);
+        printErrors(errors);
+    }
+    if (errors.length > 0)
+        process.exit(1);
+}
+/** `uwmd portfolio edges <sidecar.uwportfolio.json> [--entity <id>] [--json]` */
+export function cmdPortfolioEdges(path, flags) {
+    const candidate = readJSONFile(path);
+    const errors = validatePortfolioProfile(candidate);
+    if (errors.length > 0) {
+        console.error(`Refusing to project an invalid profile — run \`uwmd portfolio validate ${path}\`.`);
+        printErrors(errors);
+        process.exit(1);
+    }
+    const entityId = typeof flags['entity'] === 'string' ? flags['entity'] : undefined;
+    const edges = getPortfolioRelationships(candidate, entityId);
+    if (flags['json']) {
+        console.log(JSON.stringify(edges, null, 2));
+    }
+    else {
+        for (const e of edges) {
+            console.log(`${e.id}: ${e.from} —${e.type}→ ${e.to} (${e.provenance.length} provenance)`);
+        }
+        if (edges.length === 0)
+            console.log('(no edges)');
+    }
+}
+//# sourceMappingURL=cli-portfolio.js.map

package/dist/cli-portfolio.js.map

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

package/dist/cli.js

@@ -21,6 +21,7 @@ import { migrateToV2 } from './migrate-to-v2.js';
 import { REFERENCE_IMPLEMENTATION_MANIFEST } from './protocol.js';
 import { loadModuleManifest, createModuleRegistry, ModuleRegistryError } from './modules.js';
 import { cmdLeaseValidate, cmdLeaseProject, cmdPackageCreate, cmdPackageVerify, cmdPackageList, cmdPackageToContext, cmdPackageContextValidate, cmdPackageEdges, } from './cli-packages.js';
+import { cmdPortfolioValidate, cmdPortfolioEdges } from './cli-portfolio.js';
 import { evaluateCalc } from './calc/index.js';
 import { buildAgentContext, buildAgentPrompt, isContextReady, BANCROFT_LAYERS } from './context.js';
 import { runBancroftAgent } from './agents/bancroft.js';
@@ -393,7 +394,13 @@ function cmdDiff(fileA, fileB) {
     console.log('');
 }
 function cmdInit(flags) {
+    const requestedFormat = flags['format'];
+    if (requestedFormat !== undefined && requestedFormat !== '2.0' && requestedFormat !== '1.1') {
+        console.error(`--format must be '2.0' (default, nested _meta) or '1.1' (legacy flat shape); got '${requestedFormat}'.`);
+        process.exit(1);
+    }
     const content = generateBlankUWFile({
+        formatVersion: requestedFormat,
         dealName: flags['name'],
         address: flags['address'],
         city: flags['city'],
@@ -1554,6 +1561,29 @@ function withResolved(parsed, file, flags) {
             // surrounding prose so a driver can read it without a parser.
             console.log(JSON.stringify(REFERENCE_IMPLEMENTATION_MANIFEST, null, 2));
             break;
+        case 'portfolio': {
+            const sub = positional[0];
+            const target = positional[1];
+            if (sub === 'validate') {
+                if (!target) {
+                    console.error('Usage: uwmd portfolio validate <sidecar.uwportfolio.json> [--json]');
+                    process.exit(1);
+                }
+                cmdPortfolioValidate(target, flags);
+            }
+            else if (sub === 'edges') {
+                if (!target) {
+                    console.error('Usage: uwmd portfolio edges <sidecar.uwportfolio.json> [--entity <id>] [--json]');
+                    process.exit(1);
+                }
+                cmdPortfolioEdges(target, flags);
+            }
+            else {
+                console.error('Usage: uwmd portfolio <validate|edges> <sidecar.uwportfolio.json>');
+                process.exit(1);
+            }
+            break;
+        }
         case 'receipt': {
             const sub = positional[0];
             if (sub === 'issue') {
@@ -1609,6 +1639,7 @@ Commands:
   modules  validate|list        Validate module manifest files, or list the registry they form
   lease    validate|project     Validate a lease abstract, or project it to a rent-roll row (RFC 0018)
   package  create|verify|...    Build, verify, list, or project a UW Deal Package (RFC 0018)
+  portfolio validate|edges      Validate a .uwportfolio.json sidecar, or list its entity edges (RFC 0015)
   manifest                     Print this implementation's ImplementationManifest (conformance protocol)
   layers                       List Bancroft agent layers