@uwmd/core 1.1.0

package/dist/protocol.js

@@ -0,0 +1,714 @@
+// UW Protocol — TypeScript contract surface for conforming implementers.
+//
+// This module is the executable counterpart to spec/UW_PROTOCOL_v1.md.
+// Where the prose document defines normative behavior, this module names the
+// types implementers must satisfy and exports the BUILTIN_* tables that any
+// Tier-1+ Reader, Tier-2+ Editor, Tier-3+ Calc Host, or Tier-4 Agent Host
+// references.
+//
+// Types defined in `./types.ts` are re-used here, never duplicated. The
+// protocol surface is a layer over the format types — same way OpenAPI
+// operations are a layer over JSON Schema.
+// ─── Versioning ───────────────────────────────────────────────────────────────
+/** Semver of this protocol. Bumped independently of @uwmd/core's npm version. */
+export const PROTOCOL_VERSION = '1.2.0';
+/** Format spec version this protocol pairs with. */
+export const FORMAT_VERSION = '1.1';
+/** Default number-formatting table referenced by Part III §3.1. */
+export const DEFAULT_NUMBER_FORMAT = {
+    locale: 'en-US',
+    currency: { decimals: 0, symbol: '$' },
+    percent: { decimals: 2, multiplier: 100, suffix: '%' },
+    ratio: { decimals: 3, suffix: 'x' },
+    count: { thousands_separator: true },
+    null_display: 'n/a',
+};
+export const DEFAULT_DATE_FORMAT = {
+    locale: 'en-US',
+    default_style: 'iso',
+};
+/** Ordered cascade as a runtime value (frozen). Index === precedence. */
+export const CASCADE_ORDER = Object.freeze([
+    'user_override',
+    'user_input',
+    'investor_profile',
+    'market_data',
+    'asset_class_default',
+    'global_default',
+    'system_default',
+]);
+/**
+ * The full set of canonical short-form source tags producers stamp into
+ * `_meta.source`. The first seven values match `CascadeStep` 1:1; the
+ * remaining four are non-cascade tags retained from v1.0 for back-compat
+ * (`manual`, `ai_extracted`, `agent_computed`, `scenario_default`).
+ *
+ * `scenario_default` is retained but its meaning is sharpened to mean
+ * "value derived from a named scenario in the file or institution
+ * config." Producers needing a generic fallback SHOULD use
+ * `system_default` instead.
+ *
+ * Long-form patterns (e.g. `agent/L6-01`, `document/rent_roll`,
+ * `import:filename.pdf`) remain valid; this constant enumerates the
+ * canonical short forms only.
+ */
+export const SOURCE_TAGS = Object.freeze([
+    'user_input',
+    'user_override',
+    'manual',
+    'investor_profile',
+    'market_data',
+    'ai_extracted',
+    'agent_computed',
+    'asset_class_default',
+    'scenario_default',
+    'global_default',
+    'system_default',
+]);
+/**
+ * Curated default policies covering high-impact (section, stage) pairs in the
+ * multifamily workflow. Adopters MAY extend this set; lookups consult adopter
+ * policies first, then these defaults.
+ *
+ * Policies stack: more-specific (with field_path) wins over less-specific;
+ * within the same specificity, more-specific stage wins over wildcard.
+ */
+export const BUILTIN_INCOMPLETE_DATA_POLICIES = Object.freeze([
+    // ─── rent_roll ─────────────────────────────────────────────────────────────
+    {
+        section: 'rent_roll',
+        stage: 'scope',
+        action: { kind: 'substitute', fallback_source: 'asset_class_default' },
+        rationale: 'Scope-stage triage: assume default vacancy/occupancy.',
+    },
+    {
+        section: 'rent_roll',
+        stage: 'screening',
+        action: { kind: 'degrade' },
+        rationale: 'Screening tolerates estimates; surface as conditional.',
+    },
+    {
+        section: 'rent_roll',
+        stage: 'full_underwrite',
+        action: { kind: 'halt' },
+        rationale: 'Full underwrite requires the actual rent roll.',
+    },
+    // ─── noi_model ─────────────────────────────────────────────────────────────
+    {
+        section: 'noi_model',
+        field_path: 'expense_ratio',
+        stage: 'scope',
+        action: { kind: 'substitute', fallback_source: 'asset_class_default' },
+    },
+    {
+        section: 'noi_model',
+        stage: 'scope',
+        action: { kind: 'substitute', fallback_source: 'asset_class_default' },
+    },
+    {
+        section: 'noi_model',
+        stage: 'screening',
+        action: { kind: 'degrade' },
+    },
+    {
+        section: 'noi_model',
+        stage: 'full_underwrite',
+        action: { kind: 'halt' },
+        rationale: 'Full underwrite requires a T-12 / proforma derived NOI.',
+    },
+    // ─── debt_structure ────────────────────────────────────────────────────────
+    {
+        section: 'debt_structure',
+        stage: 'scope',
+        action: { kind: 'substitute', fallback_source: 'asset_class_default' },
+    },
+    {
+        section: 'debt_structure',
+        stage: 'screening',
+        action: { kind: 'substitute', fallback_source: 'investor_profile' },
+    },
+    {
+        section: 'debt_structure',
+        stage: 'term_sheet',
+        action: { kind: 'halt' },
+        rationale: 'Term sheet stage requires concrete debt terms.',
+    },
+    // ─── valuation ─────────────────────────────────────────────────────────────
+    {
+        section: 'valuation',
+        stage: 'scope',
+        action: { kind: 'substitute', fallback_source: 'asset_class_default' },
+    },
+    {
+        section: 'valuation',
+        stage: 'full_underwrite',
+        action: { kind: 'halt' },
+    },
+    // ─── borrower_sponsor ──────────────────────────────────────────────────────
+    {
+        section: 'borrower_sponsor',
+        stage: 'screening',
+        action: { kind: 'defer' },
+        rationale: 'Sponsor diligence often arrives later; record but allow advance.',
+    },
+    {
+        section: 'borrower_sponsor',
+        stage: 'credit_approval',
+        action: { kind: 'halt' },
+    },
+    // ─── compliance ────────────────────────────────────────────────────────────
+    {
+        section: 'compliance',
+        stage: 'closing',
+        action: { kind: 'halt' },
+        rationale: 'Compliance gaps cannot be carried into closing.',
+    },
+]);
+/**
+ * Look up the most-specific applicable policy for `(section, field_path, stage)`.
+ *
+ * Specificity order (highest to lowest):
+ *   1. matching section + matching field_path + matching stage
+ *   2. matching section + matching field_path (any stage)
+ *   3. matching section + matching stage (any field)
+ *   4. matching section (any field, any stage)
+ *
+ * Returns null when no policy matches.
+ */
+export function lookupIncompleteDataPolicy(section, field_path, stage, policies = BUILTIN_INCOMPLETE_DATA_POLICIES) {
+    let best = null;
+    let bestScore = -1;
+    for (const p of policies) {
+        if (p.section !== section)
+            continue;
+        const fieldMatch = p.field_path === undefined || p.field_path === field_path;
+        if (!fieldMatch)
+            continue;
+        const stageMatch = p.stage === undefined || p.stage === stage;
+        if (!stageMatch)
+            continue;
+        let score = 0;
+        if (p.field_path !== undefined)
+            score += 4;
+        if (p.stage !== undefined)
+            score += 2;
+        // Tie-break: prefer policies for the exact stage over wildcard, even if
+        // both have field_path defined.
+        if (p.stage === stage)
+            score += 1;
+        if (score > bestScore) {
+            bestScore = score;
+            best = p;
+        }
+    }
+    return best;
+}
+// ─── Built-in tables ──────────────────────────────────────────────────────────
+/**
+ * View models for the 21 standard sections defined in UW_FORMAT_SPEC_v1.md §4.
+ * Implementers SHOULD use these as the default rendering layout. Modules MAY
+ * override per-section by declaring their own `view_models` entry.
+ */
+export const BUILTIN_VIEW_MODELS = Object.freeze({
+    property: {
+        section_id: 'property',
+        display_name: 'Property',
+        display_order: 0,
+        description: 'Physical asset description: units, vintage, class, amenities.',
+        primary_fields: [
+            { path: 'total_units', label: 'Units', kind: 'count', primary: true, unit: 'units' },
+            { path: 'year_built', label: 'Built', kind: 'count' },
+            { path: 'building_class', label: 'Class', kind: 'enum', enum: ['A', 'B', 'C', 'D'] },
+            { path: 'asset_subtype', label: 'Subtype', kind: 'string' },
+        ],
+        detail_fields: [
+            { path: 'year_renovated', label: 'Renovated', kind: 'count' },
+            { path: 'total_nra_sqft', label: 'NRA', kind: 'count', unit: 'sqft' },
+            { path: 'land_area_acres', label: 'Land', kind: 'ratio', decimals: 2, unit: 'acres' },
+            { path: 'parking_spaces', label: 'Parking', kind: 'count', unit: 'spaces' },
+            { path: 'zoning', label: 'Zoning', kind: 'string' },
+            { path: 'condition', label: 'Condition', kind: 'string' },
+            { path: 'deferred_maintenance_est', label: 'Deferred Maint', kind: 'currency' },
+            { path: 'amenities', label: 'Amenities', kind: 'list' },
+        ],
+    },
+    rent_roll: {
+        section_id: 'rent_roll',
+        display_name: 'Rent Roll',
+        display_order: 1,
+        description: 'Unit-level lease detail and current rent state.',
+        primary_fields: [
+            { path: 'total_units', label: 'Total Units', kind: 'count', primary: true },
+            { path: 'occupied_units', label: 'Occupied', kind: 'count', primary: true },
+            { path: 'physical_occupancy', label: 'Occupancy', kind: 'percent', primary: true },
+            { path: 'avg_rent', label: 'Avg Rent', kind: 'currency' },
+        ],
+    },
+    noi_model: {
+        section_id: 'noi_model',
+        display_name: 'NOI Model',
+        display_order: 2,
+        description: 'Underwritten T-12 normalized operating statement.',
+        primary_fields: [
+            { path: 'net_operating_income', label: 'NOI', kind: 'currency', primary: true },
+            { path: 'effective_gross_income', label: 'EGI', kind: 'currency' },
+            { path: 'total_operating_expenses', label: 'OpEx', kind: 'currency' },
+            { path: 'opex_ratio', label: 'OpEx Ratio', kind: 'percent' },
+        ],
+        detail_fields: [
+            { path: 'gross_potential_rent', label: 'GPR', kind: 'currency' },
+            { path: 'vacancy_loss', label: 'Vacancy Loss', kind: 'currency' },
+            { path: 'vacancy_rate', label: 'Vacancy Rate', kind: 'percent' },
+            { path: 'other_income', label: 'Other Income', kind: 'currency' },
+        ],
+    },
+    debt_structure: {
+        section_id: 'debt_structure',
+        display_name: 'Debt',
+        display_order: 3,
+        description: 'Loan terms and computed debt metrics.',
+        primary_fields: [
+            { path: 'loan_amount', label: 'Loan', kind: 'currency', primary: true },
+            { path: 'interest_rate', label: 'Rate', kind: 'percent', primary: true },
+            { path: 'dscr', label: 'DSCR', kind: 'ratio', primary: true },
+            { path: 'ltv', label: 'LTV', kind: 'percent', primary: true },
+        ],
+        detail_fields: [
+            { path: 'loan_term_years', label: 'Term', kind: 'count', unit: 'yrs' },
+            { path: 'amortization_years', label: 'Amortization', kind: 'count', unit: 'yrs' },
+            { path: 'io_period_months', label: 'IO Period', kind: 'count', unit: 'mo' },
+            { path: 'debt_yield', label: 'Debt Yield', kind: 'percent' },
+            { path: 'annual_debt_service', label: 'Annual DS', kind: 'currency' },
+            { path: 'recourse', label: 'Recourse', kind: 'string' },
+        ],
+    },
+    valuation: {
+        section_id: 'valuation',
+        display_name: 'Valuation',
+        display_order: 4,
+        description: 'Purchase price, underwritten value, comparable analysis.',
+        primary_fields: [
+            { path: 'purchase_price', label: 'Purchase Price', kind: 'currency', primary: true },
+            { path: 'underwritten_value', label: 'UW Value', kind: 'currency' },
+            { path: 'going_in_cap_rate', label: 'Going-in Cap', kind: 'percent', primary: true },
+            { path: 'price_per_unit', label: 'Price/Unit', kind: 'currency' },
+        ],
+    },
+    dcf: {
+        section_id: 'dcf',
+        display_name: 'DCF',
+        display_order: 5,
+        description: 'Discounted cash flow, hold-period assumptions, IRR.',
+        primary_fields: [
+            { path: 'levered_irr', label: 'Levered IRR', kind: 'percent', primary: true },
+            { path: 'levered_equity_multiple', label: 'Equity Multiple', kind: 'ratio', primary: true },
+            { path: 'assumptions.hold_period_years', label: 'Hold', kind: 'count', unit: 'yrs' },
+            { path: 'assumptions.exit_cap_rate', label: 'Exit Cap', kind: 'percent' },
+        ],
+    },
+    sources_uses: {
+        section_id: 'sources_uses',
+        display_name: 'Sources & Uses',
+        display_order: 6,
+        description: 'Capital stack reconciliation.',
+        primary_fields: [
+            { path: 'total_sources', label: 'Total Sources', kind: 'currency', primary: true },
+            { path: 'total_uses', label: 'Total Uses', kind: 'currency', primary: true },
+        ],
+    },
+    market_analysis: {
+        section_id: 'market_analysis',
+        display_name: 'Market',
+        display_order: 7,
+        description: 'MSA / submarket fundamentals and comp set.',
+        primary_fields: [
+            { path: 'msa', label: 'MSA', kind: 'string', primary: true },
+            { path: 'market_vacancy_rate', label: 'Market Vacancy', kind: 'percent' },
+            { path: 'average_asking_rent', label: 'Asking Rent', kind: 'currency' },
+            { path: 'recent_rent_growth', label: 'Rent Growth', kind: 'percent' },
+        ],
+    },
+    borrower_sponsor: {
+        section_id: 'borrower_sponsor',
+        display_name: 'Sponsor',
+        display_order: 8,
+        description: 'Borrower / sponsor financial strength.',
+        primary_fields: [
+            { path: 'name', label: 'Sponsor', kind: 'string', primary: true },
+            { path: 'net_worth', label: 'Net Worth', kind: 'currency' },
+            { path: 'liquidity', label: 'Liquidity', kind: 'currency' },
+            { path: 'years_experience', label: 'Experience', kind: 'count', unit: 'yrs' },
+        ],
+    },
+    deal_context: {
+        section_id: 'deal_context',
+        display_name: 'Deal Context',
+        display_order: 9,
+        description: 'Investment thesis, value creation, hold strategy narrative.',
+        primary_fields: [
+            { path: 'investment_thesis', label: 'Thesis', kind: 'string', primary: true },
+            { path: 'value_creation_strategy', label: 'Value Creation', kind: 'string' },
+            { path: 'hold_strategy', label: 'Hold Strategy', kind: 'string' },
+        ],
+    },
+    stress_tests: {
+        section_id: 'stress_tests',
+        display_name: 'Stress Tests',
+        display_order: 10,
+        description: 'Sensitivity scenarios — vacancy, rate, exit cap shocks.',
+        multi_variant: true,
+        primary_fields: [
+            { path: 'name', label: 'Scenario', kind: 'string', primary: true },
+            { path: 'dscr', label: 'DSCR', kind: 'ratio' },
+            { path: 'irr', label: 'IRR', kind: 'percent' },
+        ],
+    },
+    risk_assessment: {
+        section_id: 'risk_assessment',
+        display_name: 'Risk Assessment',
+        display_order: 11,
+        description: 'Aggregate risk rating and key risk factors.',
+        primary_fields: [
+            { path: 'overall_rating', label: 'Rating', kind: 'string', primary: true },
+            { path: 'risk_score', label: 'Score', kind: 'count' },
+            { path: 'key_risks', label: 'Key Risks', kind: 'list' },
+        ],
+    },
+    // Remaining standard sections registered with minimal hints; implementers
+    // may pull richer view models from their own modules.
+    loan_terms_summary: {
+        section_id: 'loan_terms_summary', display_name: 'Loan Terms Summary', display_order: 12,
+        description: 'Term sheet summary issued to borrower.',
+        primary_fields: [],
+    },
+    closing_conditions: {
+        section_id: 'closing_conditions', display_name: 'Closing Conditions', display_order: 13,
+        description: 'CPs, post-close covenants, reserve requirements.',
+        primary_fields: [],
+    },
+    third_party_reports: {
+        section_id: 'third_party_reports', display_name: 'Third-Party Reports', display_order: 14,
+        description: 'Appraisal, PCA, ESA, zoning, survey status.',
+        primary_fields: [],
+    },
+    insurance: {
+        section_id: 'insurance', display_name: 'Insurance', display_order: 15,
+        description: 'Required coverages and current binder status.',
+        primary_fields: [],
+    },
+    environmental: {
+        section_id: 'environmental', display_name: 'Environmental', display_order: 16,
+        description: 'Phase I / II findings and recognized environmental conditions.',
+        primary_fields: [],
+    },
+    legal: {
+        section_id: 'legal', display_name: 'Legal', display_order: 17,
+        description: 'Title, survey, entity structure, ongoing litigation.',
+        primary_fields: [],
+    },
+    compliance: {
+        section_id: 'compliance', display_name: 'Compliance', display_order: 18,
+        description: 'BSA/AML, OFAC, fair-lending, regulatory checks.',
+        primary_fields: [],
+    },
+    monitoring: {
+        section_id: 'monitoring', display_name: 'Monitoring', display_order: 19,
+        description: 'Post-close performance tracking and covenant compliance.',
+        primary_fields: [],
+    },
+    recommendation: {
+        section_id: 'recommendation', display_name: 'Recommendation', display_order: 20,
+        description: 'Final credit recommendation and rationale.',
+        primary_fields: [
+            { path: 'decision', label: 'Decision', kind: 'string', primary: true },
+            { path: 'rationale', label: 'Rationale', kind: 'string' },
+        ],
+    },
+    gaps: {
+        section_id: 'gaps', display_name: 'Gaps', display_order: 21,
+        description: 'Open data gaps blocking stage advancement or carrying provisional defaults. Maintained by the editor when --maintain-gaps is on; otherwise hand-curated.',
+        primary_fields: [
+            { path: 'summary.total_open', label: 'Open', kind: 'count', primary: true },
+            { path: 'summary.blocking_current_stage', label: 'Blocking Current', kind: 'count' },
+            { path: 'summary.blocking_next_stage', label: 'Blocking Next', kind: 'count' },
+        ],
+    },
+});
+/**
+ * Default edit policies derived from canonical `_meta.source` patterns.
+ * Implementers consult this table to decide whether a write is a replace
+ * or a supersede, and whether the actor is permitted to write at all.
+ */
+export const BUILTIN_EDIT_POLICIES = Object.freeze([
+    { source_pattern: 'agent/*', authority: 'either', supersede_on_edit: true },
+    { source_pattern: 'manual', authority: 'either', supersede_on_edit: false },
+    { source_pattern: 'document/*', authority: 'either', supersede_on_edit: true },
+    { source_pattern: 'system/*', authority: 'system_only', supersede_on_edit: false },
+    { source_pattern: 'institution/*', authority: 'system_only', supersede_on_edit: false },
+]);
+/**
+ * Remediation copy for the cross-cutting consistency checks CC-01..CC-10
+ * (see UW_FORMAT_SPEC_v1.md §5.3). Renderers SHOULD surface these strings
+ * verbatim in any validation issue list — the goal is uniform UX across
+ * every conforming implementation.
+ */
+export const BUILTIN_REMEDIATIONS = Object.freeze([
+    {
+        code: 'CC-01', severity: 'error',
+        title: 'NOI mismatch',
+        description: 'noi_model.net_operating_income disagrees with quick_metrics.noi_underwritten.',
+        remediation: 'Recompute NOI from the noi_model section and update frontmatter.quick_metrics.noi_underwritten.',
+        spec_ref: '§5.3 CC-01',
+    },
+    {
+        code: 'CC-02', severity: 'error',
+        title: 'DSCR mismatch',
+        description: 'debt_structure.dscr disagrees with quick_metrics.dscr.',
+        remediation: 'Recompute DSCR = NOI / annual_debt_service and update both surfaces.',
+        spec_ref: '§5.3 CC-02',
+    },
+    {
+        code: 'CC-03', severity: 'error',
+        title: 'LTV mismatch',
+        description: 'debt_structure.ltv disagrees with quick_metrics.ltv.',
+        remediation: 'Recompute LTV = loan_amount / purchase_price and update both surfaces.',
+        spec_ref: '§5.3 CC-03',
+    },
+    {
+        code: 'CC-04', severity: 'error',
+        title: 'Sources & Uses imbalance',
+        description: 'sources_uses.total_sources does not equal total_uses.',
+        remediation: 'Reconcile capital stack — equity + debt proceeds + other sources MUST equal price + closing + reserves.',
+        spec_ref: '§5.3 CC-04',
+    },
+    {
+        code: 'CC-05', severity: 'error',
+        title: 'Cap rate mismatch',
+        description: 'valuation.going_in_cap_rate disagrees with quick_metrics.cap_rate.',
+        remediation: 'Recompute cap rate = NOI / purchase_price and align both surfaces.',
+        spec_ref: '§5.3 CC-05',
+    },
+    {
+        code: 'CC-06', severity: 'warning',
+        title: 'Debt yield mismatch',
+        description: 'debt_structure.debt_yield disagrees with quick_metrics.debt_yield.',
+        remediation: 'Recompute debt yield = NOI / loan_amount and align both surfaces.',
+        spec_ref: '§5.3 CC-06',
+    },
+    {
+        code: 'CC-07', severity: 'warning',
+        title: 'IRR / equity multiple mismatch',
+        description: 'dcf.levered_irr disagrees with quick_metrics.irr_projected.',
+        remediation: 'Re-run the DCF and update quick_metrics.irr_projected from dcf.levered_irr.',
+        spec_ref: '§5.3 CC-07',
+    },
+    {
+        code: 'CC-08', severity: 'error',
+        title: 'Equity required mismatch',
+        description: 'sources_uses-derived equity disagrees with quick_metrics.equity_required.',
+        remediation: 'Set quick_metrics.equity_required = sources_uses.sources.equity.',
+        spec_ref: '§5.3 CC-08',
+    },
+    {
+        code: 'CC-09', severity: 'warning',
+        title: 'Stage readiness gap',
+        description: 'A required section for the declared deal_stage is missing or low-confidence.',
+        remediation: 'Either complete the required sections for this stage or downgrade frontmatter.deal_stage.',
+        spec_ref: '§5.3 CC-09',
+    },
+    {
+        code: 'CC-10', severity: 'info',
+        title: 'Stale provenance',
+        description: 'A section\'s _meta.timestamp is older than the file last_modified by more than 30 days.',
+        remediation: 'Refresh the section, supersede with a new agent/manual write, or mark deliberate stale.',
+        spec_ref: '§5.3 CC-10',
+    },
+    {
+        code: 'DQ-01', severity: 'warning',
+        title: 'Provisional block without gap entry',
+        description: 'A block is marked _meta.provisional=true but no entry in the `gaps` section references it.',
+        remediation: 'Add a `gaps` item naming this section/path (or run editor with --maintain-gaps), or remove the provisional flag.',
+        spec_ref: 'UW_FORMAT_SPEC_v1.md §3.4 / §4.22',
+    },
+    {
+        code: 'DQ-02', severity: 'error',
+        title: 'Provisional value consumed at incompatible stage',
+        description: 'A provisional / placeholder value is being consumed at a stage whose policy requires real data.',
+        remediation: 'Replace the provisional value with observed data, downgrade deal_stage, or update INCOMPLETE_DATA_POLICIES if appropriate.',
+        spec_ref: 'UW_PROTOCOL_v1.md §V.7-§V.8',
+    },
+    {
+        code: 'DQ-03', severity: 'warning',
+        title: 'Partial block without field-level enumeration',
+        description: 'A block is marked _meta.partial=true but has no _meta.field_overrides[] enumeration.',
+        remediation: 'List the affected paths in field_overrides with reason ("missing"|"illegible"|"estimated").',
+        spec_ref: 'UW_FORMAT_SPEC_v1.md §3.4',
+    },
+    {
+        code: 'DQ-04', severity: 'error',
+        title: 'Scope-stage readiness gap',
+        description: 'A field required for scope-stage readiness is missing.',
+        remediation: 'Provide the missing scope-stage field (property.address, property.asset_class, and at least one of property.units or property.asking_price) or downgrade deal_stage.',
+        spec_ref: 'UW_FORMAT_SPEC_v1.md §2.2',
+    },
+    {
+        code: 'DQ-05', severity: 'info',
+        title: 'Stale gap',
+        description: 'A `gaps` item has not been re-checked recently and may be obsolete.',
+        remediation: 'Re-check the gap and refresh `last_checked`, or close the gap if it has been resolved.',
+        spec_ref: 'UW_FORMAT_SPEC_v1.md §4.22',
+    },
+    // ─── Integrity (INT-NN) — content_hash / parent_hash chain checks ──────────
+    {
+        code: 'INT-01', severity: 'error',
+        title: 'Parent hash mismatch',
+        description: 'A block\'s _meta.parent_hash does not equal the prior block\'s _meta.content_hash in the supersede chain.',
+        remediation: 'Recompute the block from the current head: stamp parent_hash with the prior block\'s content_hash and bump the version.',
+        spec_ref: 'UW_PROTOCOL_v1.md §V.10',
+    },
+    {
+        code: 'INT-02', severity: 'error',
+        title: 'Stale parent hash on edit',
+        description: 'applyEdit was invoked with a parent_hash that does not match the current head of the section.',
+        remediation: 'Re-read the file, take the latest head\'s content_hash, and retry the edit with the fresh parent_hash.',
+        spec_ref: 'UW_PROTOCOL_v1.md §V.10',
+    },
+    {
+        code: 'INT-03', severity: 'warning',
+        title: 'Partially hashed chain',
+        description: 'Some blocks in a supersede chain carry _meta.content_hash and others do not.',
+        remediation: 'Once any block in a chain is hashed, every subsequent block MUST be hashed; rehash the unstamped blocks.',
+        spec_ref: 'UW_PROTOCOL_v1.md §V.10',
+    },
+    {
+        code: 'INT-04', severity: 'warning',
+        title: 'Content hash does not recompute',
+        description: 'A block\'s stamped _meta.content_hash does not match the SHA-256 of its current canonicalized content.',
+        remediation: 'Either restore the original content or re-stamp content_hash from the current canonicalized form.',
+        spec_ref: 'UW_PROTOCOL_v1.md §V.9',
+    },
+    // ─── Provenance / policy (POL-NN) — actor and operation authority ──────────
+    {
+        code: 'POL-01', severity: 'error',
+        title: 'Unauthorized actor',
+        description: 'The block\'s _meta.actor is not authorized to write this section per its EditPolicy.',
+        remediation: 'Re-issue the edit from an actor allowed by the section\'s policy (see BUILTIN_EDIT_POLICIES).',
+        spec_ref: 'UW_PROTOCOL_v1.md §VIII',
+    },
+    {
+        code: 'POL-02', severity: 'error',
+        title: 'Replace where supersede is required',
+        description: 'The section\'s policy requires supersede_on_edit but the head version > 1 has no superseded prior versions.',
+        remediation: 'Re-issue the edit as section_supersede so the prior version is preserved as a superseded block.',
+        spec_ref: 'UW_PROTOCOL_v1.md §VIII',
+    },
+    // ─── Financial validity (FV-NN) — renamed from FV_* in v1.1 ────────────────
+    // Severity is the *highest* severity any emission of this code can carry
+    // (e.g. FV-04 may be warning OR error depending on threshold).
+    {
+        code: 'FV-01', severity: 'warning',
+        title: 'Cap rate below threshold',
+        description: 'Going-in cap rate is below the configured warning threshold.',
+        remediation: 'Verify NOI and purchase price; an unusually low cap rate often indicates an aggressive valuation.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-02', severity: 'warning',
+        title: 'Cap rate above threshold',
+        description: 'Going-in cap rate is above the configured warning threshold.',
+        remediation: 'A high cap rate may indicate distressed pricing or market dislocation; confirm the underwriting story.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-03', severity: 'warning',
+        title: 'Debt yield below threshold',
+        description: 'Debt yield is below the configured warning threshold.',
+        remediation: 'Re-check NOI and loan amount; consider a smaller loan or higher equity.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-04', severity: 'error',
+        title: 'DSCR below threshold',
+        description: 'DSCR is below the configured threshold (warning or error).',
+        remediation: 'Re-size the loan, lower the rate assumption, or increase NOI to meet the lender constraint.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-05', severity: 'warning',
+        title: 'Equity multiple below minimum',
+        description: 'Levered equity multiple is below the configured minimum.',
+        remediation: 'Re-examine hold period, exit assumptions, and capital structure.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-06', severity: 'warning',
+        title: 'Equity multiple above maximum',
+        description: 'Levered equity multiple is above the configured maximum (likely unrealistic).',
+        remediation: 'Sanity-check exit cap, rent growth, and hold-period assumptions.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-07', severity: 'warning',
+        title: 'IRR below threshold',
+        description: 'Levered IRR is below the configured warning threshold.',
+        remediation: 'Verify the projected exit value and cash-flow trajectory.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-08', severity: 'warning',
+        title: 'IRR above threshold',
+        description: 'Levered IRR is above the configured warning threshold (likely unrealistic).',
+        remediation: 'An IRR over the upper threshold usually signals an aggressive exit cap or rent-growth assumption.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-09', severity: 'error',
+        title: 'LTV above threshold',
+        description: 'LTV is above the configured threshold (warning or error).',
+        remediation: 'Reduce loan size or increase appraised value support.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-10', severity: 'warning',
+        title: 'OpEx ratio below minimum',
+        description: 'OpEx as a share of EGI is suspiciously low.',
+        remediation: 'Verify that all operating line items are captured (taxes, insurance, management, R&M, payroll, utilities).',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-11', severity: 'warning',
+        title: 'OpEx ratio above maximum',
+        description: 'OpEx as a share of EGI is unusually high.',
+        remediation: 'Investigate one-time items, deferred maintenance, or below-market rents.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-12', severity: 'warning',
+        title: 'Annual rent growth above threshold',
+        description: 'Annual rent growth assumption exceeds the configured threshold.',
+        remediation: 'Tie rent growth to a published submarket forecast or document the rationale.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-13', severity: 'warning',
+        title: 'Vacancy below minimum',
+        description: 'Vacancy assumption is below the configured floor.',
+        remediation: 'Use the higher of submarket stabilized vacancy or institutional minimum.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'FV-14', severity: 'warning',
+        title: 'Vacancy above maximum',
+        description: 'Vacancy assumption is above the configured warning threshold.',
+        remediation: 'A vacancy over the upper threshold usually indicates lease-up or distress; re-examine the value-creation story.',
+        spec_ref: '§5.2',
+    },
+    {
+        code: 'UNSUPPORTED_YAML_FEATURE', severity: 'error',
+        title: 'Unsupported YAML feature in frontmatter',
+        description: 'Frontmatter uses a YAML feature outside the .uw.md subset (anchors, tags, block scalars, complex keys, or directives).',
+        remediation: 'Rewrite the frontmatter using only the YAML subset documented in UW_FORMAT_SPEC_v1.md Appendix A — scalars, simple mappings, and dash-prefixed sequences.',
+        spec_ref: 'UW_FORMAT_SPEC_v1.md Appendix A',
+    },
+]);
+//# sourceMappingURL=protocol.js.map