phoenix-waterfall-ledger-semantics

Phoenix Waterfall Ledger Semantics

You own GP/LP waterfall semantics for both the tier-based and ledger-based engines, including shortfall-based partial clawback and cross-validation rules.

When to Use

Invoke this skill when:

• Editing server/analytics/waterfall-tier.ts or server/analytics/waterfall-ledger.ts
• Working on clawback behavior or validating scenario L08 and related cases
• Expanding or debugging waterfall truth-case JSONs
• Syncing waterfall docs/JSDoc with actual behavior

Files You Own

• Implementation:
  • server/analytics/waterfall-tier.ts
  • server/analytics/waterfall-ledger.ts
• Types / config:
  • shared/types/waterfall.ts (or equivalent config types)
• Truth cases:
  • docs/waterfall-tier.truth-cases.json
  • docs/waterfall-ledger.truth-cases.json
• Documentation:
  • Waterfall section in docs/calculations.md
  • Clawback JSDoc in the waterfall config types

Core Concepts

Tier vs. Ledger

• Tier engine:

  • Simple tiers (return of capital, preferred, carry splits)
  • No ledger-level clawback

• Ledger engine:

  • Full ledger of contributions and distributions
  • Applies shortfall-based partial clawback:
    • GP carry is limited by fund-level profit above the LP shortfall
    • If LPs haven't achieved capital + preferred return, GP carry is reduced proportionally
    • Not a binary all-or-nothing clawback
    • Not time-based; uses cumulative fund performance at liquidation

Only for simple, no-clawback, no-recycling cases may tier and ledger results be expected to match.

Clawback Semantics

Ensure implementation and docs agree:

• Use a shortfall-based formula:
  • LP shortfall = (required capital + pref) – actual LP distributions
  • GP clawback = min(GP carry, LP shortfall)
• JSDoc must clearly state:
  • "Shortfall-based partial clawback (NOT hard floor, NOT time-based)"
  • Include a concrete example referencing the relevant truth case (e.g., L08)

Truth-Case Workflow

1. Identify failing scenario(s) in tier/ledger truth-cases JSON.

2. Run targeted tests:

   npm test -- tests/truth-cases/runner.test.ts -t "<scenario-id>"
   

3. Compare:

   • Expected vs actual totals (LP distributions, GP carry, clawback)
   • Row-level distributions for ledger scenarios (e.g., quarterly rows)

4. Decide:

   • JSON wrong → fix truth case and re-run
   • Implementation wrong → adjust code, keep semantics aligned with docs and plan

Documentation Sync

Whenever you change behavior:

• Update:
  • docs/calculations.md waterfall section
  • JSDoc for waterfall config and key functions
• Include:
  • Plain-English description of clawback behavior
  • Example using a real truth-case ID

Invariants

• Clawback must never cause LPs to receive less than capital + pref while GP receives carry.
• Ledger engine must respect the LPA semantics described in the plan and JSDoc.
• Tier engine is not used to validate clawback scenarios.