{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://uwmd.org/schemas/section-distribution-waterfall.schema.json",
  "title": "UW Markdown Distribution Waterfall Section",
  "description": "Content payload for the `distribution_waterfall` section (UW_FORMAT_SPEC.md §4.27, RFC 0035 + RFC 0036 + RFC 0051). The tiered LP/GP split of a deal's equity cash flows — return of capital, preferred return, GP catch-up, and promote splits — over a referenced `cash_flow_series` variant (§4.26). The fourth state-and-verify structure (RFC 0021 §6): `verifyWaterfall` recomputes the ENTIRE allocation by the normative Protocol §VIII.10 walk, never trusting the stated splits. This schema enforces structure only. The cross-field rules a validator/verifier adds: the ladder grammar incl. ordering, singleton, terminal-uncapped-split, sum-to-one, gp_share>target_promote, and strictly-increasing hurdle-ladder rules (WF-01); the cash reference resolving in-document (WF-02); at least one contribution in the referenced series (WF-03); and every stated outcome/schedule cell recomputing at its quantization boundary or the verdict is `failed`. RFC0096 WF-16 owns typed stated outcomes/schedule and unused clawback floors/extra members; selected floors and financial rules retain existing owners.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "cash_flow_ref",
    "equity_split",
    "tiers"
  ],
  "properties": {
    "_role": {
      "enum": [
        "primary",
        "senior",
        "junior",
        "summary",
        "detail",
        "component"
      ],
      "description": "Optional signed scalar block annotation (RFC 0040)."
    },
    "_meta": {
      "type": "object",
      "description": "Standard block provenance envelope (§2.5). Not constrained here."
    },
    "_notes": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional free-text annotation (§4 universal field)."
    },
    "cash_flow_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "variant"
      ],
      "description": "The §4.26 cash_flow_series variant holding the EQUITY cash vector: negative amounts are contributions, positive amounts are distributable cash. Its day_count governs every year fraction here.",
      "properties": {
        "variant": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "equity_split": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "lp",
        "gp"
      ],
      "description": "Each party's share of every contribution; must sum to 1.0 (ratio quantum, WF-01). The GP share is co-invest; the promote comes from the tiers.",
      "properties": {
        "lp": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "gp": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "tiers": {
      "type": "array",
      "minItems": 1,
      "description": "The ordered ladder: return_of_capital? → preferred_return? → catch_up? → split+ with an uncapped final split (WF-01).",
      "items": {
        "$ref": "#/$defs/tier"
      }
    },
    "clawback": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "description": "RFC 0059 clawback: a terminal true-up, never per-period state.",
      "required": [
        "basis",
        "cap"
      ],
      "properties": {
        "basis": {
          "enum": [
            "lp_preferred_shortfall",
            "lp_irr_floor",
            "lp_em_floor"
          ],
          "description": "Closed vocabulary (WF-10). lp_preferred_shortfall needs a preferred_return tier (WF-11)."
        },
        "floor_rate": {
          "type": [
            "number",
            "null"
          ],
          "exclusiveMinimum": 0,
          "exclusiveMaximum": 1,
          "description": "Fraction, required for lp_irr_floor. 0.12 is 12%."
        },
        "floor_multiple": {
          "type": [
            "number",
            "null"
          ],
          "exclusiveMinimum": 1,
          "description": "Required for lp_em_floor."
        },
        "net_of_tax_rate": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "exclusiveMaximum": 1,
          "description": "Stated and applied, never derived (WF-13)."
        },
        "cap": {
          "const": "promote_received",
          "description": "The only cap (WF-12): a GP cannot return more promote than it received."
        }
      }
    },
    "stated_outcomes": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "description": "Headline claims, each verified when present (quanta: $→2, x→4, %→6).",
      "properties": {
        "lp": {
          "$ref": "#/$defs/party_outcomes"
        },
        "gp": {
          "$ref": "#/$defs/party_outcomes"
        },
        "promote_total": {
          "type": [
            "number",
            "null"
          ],
          "description": "GP distributions above its returned capital + pref receipts."
        },
        "profit_total": {
          "type": [
            "number",
            "null"
          ]
        },
        "clawback_amount": {
          "type": [
            "number",
            "null"
          ],
          "description": "RFC 0059 terminal true-up. Unverifiable when no clawback provision is declared; 0 means the LP cleared its floor."
        }
      }
    },
    "stated_schedule": {
      "type": [
        "array",
        "null"
      ],
      "description": "Optional per-date distribution detail, one entry per distribution date; checked cell-for-cell against the recomputed allocation, with absent cells reading 0. Display detail — the verifier recomputes regardless.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "date",
          "by_tier"
        ],
        "properties": {
          "date": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}(?![\\s\\S])",
            "description": "WF-16 whole-input ASCII lexical shape only, without Gregorian/year-range admission or a format plugin."
          },
          "by_tier": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "tier"
              ],
              "properties": {
                "tier": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Index into `tiers`."
                },
                "lp": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "gp": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "$defs": {
    "party_outcomes": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "properties": {
        "contributions": {
          "type": [
            "number",
            "null"
          ]
        },
        "distributions": {
          "type": [
            "number",
            "null"
          ]
        },
        "moic": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0
        },
        "xirr": {
          "type": [
            "number",
            "null"
          ],
          "description": "Fraction, recomputed by the §VIII.9.3 procedure over the party's dated flows."
        }
      }
    },
    "tier": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "type"
          ],
          "properties": {
            "type": {
              "const": "return_of_capital"
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "type",
            "rate",
            "accrual"
          ],
          "properties": {
            "type": {
              "const": "preferred_return"
            },
            "rate": {
              "type": "number",
              "exclusiveMinimum": 0,
              "exclusiveMaximum": 1,
              "description": "Fraction (0.09, never 9)."
            },
            "accrual": {
              "enum": [
                "simple",
                "compound_annual"
              ],
              "description": "compound_annual: unpaid pref itself compounds (Protocol §VIII.10)."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "type",
            "gp_share",
            "target_promote"
          ],
          "properties": {
            "type": {
              "const": "catch_up"
            },
            "gp_share": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1
            },
            "target_promote": {
              "type": "number",
              "exclusiveMinimum": 0,
              "exclusiveMaximum": 1,
              "description": "gp_share MUST exceed this (WF-01) or the tier can never fill."
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "type",
            "lp_share",
            "gp_share"
          ],
          "properties": {
            "type": {
              "const": "split"
            },
            "lp_share": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "gp_share": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "until_lp_em": {
              "type": [
                "number",
                "null"
              ],
              "exclusiveMinimum": 0,
              "description": "Equity-multiple hurdle capping the tier where cumulative LP distributions reach this multiple of LP contributions; the final split must be uncapped, a capped split must have lp_share > 0, and successive stated values must strictly increase (WF-01)."
            },
            "until_lp_irr": {
              "type": [
                "number",
                "null"
              ],
              "exclusiveMinimum": 0,
              "exclusiveMaximum": 1,
              "description": "LP IRR hurdle (a fraction: 0.12, never 12) capping the tier where the LP's dated flows — including this tier's payment — reach that rate under the series' day count, by the closed-form hurdle balance (Protocol §VIII.10 step 3, RFC 0036). May be stated alongside until_lp_em; the tier then ends only when both are met (the larger capacity governs). Same terminal / lp_share / strictly-increasing rules (WF-01)."
            },
            "hurdle_mode": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "both",
                "any",
                null
              ],
              "description": "When both until_lp_em and until_lp_irr are stated, selects whether the tier ends when both hurdles are met ('both', default) or whichever is met first ('any'). Stating hurdle_mode without both hurdles is an error (WF-01, RFC 0051)."
            }
          }
        }
      ]
    }
  }
}
