> ## Documentation Index
> Fetch the complete documentation index at: https://village-docs.villagelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Design Principles

> The foundational concepts that drive the Repurchase Engine architecture

## Foundational Philosophy

The Repurchase Engine is built upon three core design principles that ensure its robustness, auditability, and extensibility. These principles inform every architectural decision and distinguish this system from traditional financial modeling tools.

<CardGroup cols={3}>
  <Card title="Separation of Concerns" icon="layer-group">
    Distinguish legal rules from business strategy
  </Card>

  <Card title="Immutability" icon="lock">
    Never overwrite; always append
  </Card>

  <Card title="Abstraction" icon="cube">
    High-level intents, not low-level functions
  </Card>
</CardGroup>

***

## Principle 1: Separation of Concerns

### Plan Rules vs. Operating Assumptions

The engine's input framework makes a **crucial distinction** between two types of information:

<Columns cols={2}>
  <div>
    ### PlanRules

    **The "Constitution"**

    The stable, legal framework of the ESOP as defined in the official plan document.

    **Characteristics:**

    * Non-discretionary
    * Legally binding
    * Changes infrequently
    * Requires plan amendments

    **Examples:**

    * Vesting schedule
    * Distribution timing
    * Diversification eligibility
    * Cash usage hierarchy
  </div>

  <div>
    ### OperatingAssumptions

    **The "Annual Strategy"**

    The discretionary, variable financial decisions made by the company on an annual basis.

    **Characteristics:**

    * Discretionary
    * Business decisions
    * Changes annually
    * No legal filing required

    **Examples:**

    * Contribution amounts
    * Share valuations
    * Repurchase timing
    * Growth assumptions
  </div>
</Columns>

### Why This Matters

<AccordionGroup>
  <Accordion title="Mirrors Real-World Operations" icon="building">
    This separation directly reflects how plan sponsors and fiduciaries actually think and operate. The plan document is the unchanging foundation, while annual business decisions vary based on financial conditions.
  </Accordion>

  <Accordion title="Simplifies Scenario Analysis" icon="code-compare">
    To compare scenarios, you simply swap out `OperatingAssumptions` while keeping `PlanRules` constant. No need to duplicate or modify legal configurations.

    ```python theme={null}
    # Scenario 1: Conservative
    conservative = engine.simulate(
        plan_rules=legal_framework,
        operating_assumptions=conservative_strategy
    )

    # Scenario 2: Aggressive
    aggressive = engine.simulate(
        plan_rules=legal_framework,  # Same rules!
        operating_assumptions=aggressive_strategy
    )
    ```
  </Accordion>

  <Accordion title="Prevents Configuration Errors" icon="shield-check">
    By structurally separating legal requirements from business decisions, the system prevents common errors like accidentally modifying vesting schedules when you meant to change contribution levels.
  </Accordion>
</AccordionGroup>

### Implementation Example

<Tabs>
  <Tab title="PlanRules">
    ```json theme={null}
    {
      "plan_name": "Acme Corp ESOP",
      "plan_year_end": "12/31",
      "vesting_schedule": {
        "type": "graded",
        "schedule": [0, 0, 20, 40, 60, 80, 100]
      },
      "distribution_policy": {
        "timing": "termination_plus_1_year",
        "form": "lump_sum",
        "in_service_allowed": false
      },
      "cash_usage_policy": [
        "unallocated_company_contributions",
        "unallocated_forfeiture_cash",
        "participant_cash_accounts"
      ]
    }
    ```

    ☝️ *These rarely change*
  </Tab>

  <Tab title="OperatingAssumptions">
    ```json theme={null}
    {
      "contribution_policy": {
        "type": "fixed_amount",
        "amount": 500000
      },
      "share_valuation": {
        "current_price": 100.00,
        "annual_growth_rate": 0.05
      },
      "repurchase_strategy": {
        "timing": "immediate",
        "funding_source": "company_contribution"
      },
      "financial_projections": {
        "revenue_growth": 0.08,
        "ebitda_margin": 0.22
      }
    }
    ```

    ☝️ *These change annually*
  </Tab>
</Tabs>

***

## Principle 2: Immutability

### The Database as a System of Record

The data layer is a **temporal, stateful, and immutable system of record**.

<Warning>
  **First Principle:** A model's credibility is tied to its reproducibility. We never overwrite data; every input scenario and simulation run is a permanent, versioned record.
</Warning>

### The Problem with Traditional Approaches

Most financial models overwrite results:

```
❌ Traditional Model:
   Run 1 (June) → results.xlsx → ✓
   Run 2 (Sept) → results.xlsx → ✓ [Run 1 data lost!]
   
   Questions:
   - What changed between runs?
   - Can we reproduce June's results?
   - Which assumptions drove the differences?
   
   Answer: 🤷 Unknown
```

### The Immutable Approach

The Repurchase Engine appends, never overwrites:

```
✅ Immutable System:
   Run 1 (June) → Scenario A v1 → SimRun #123 → Results archived
   Run 2 (Sept) → Scenario A v2 → SimRun #456 → Results archived
   
   Questions:
   - What changed? → Diff Scenario v1 vs v2
   - Reproduce June? → Replay SimRun #123
   - Compare results? → Query both runs
   
   Answer: ✅ Fully auditable
```

### Implementation

Every simulation creates permanent, timestamped records:

<Steps>
  <Step title="Input Versioning">
    ```sql theme={null}
    scenarios
      id: "scenario_2024_06_15_001"
      created_at: "2024-06-15T10:30:00Z"
      plan_rules: {...}
      operating_assumptions: {...}
      version: 1
    ```
  </Step>

  <Step title="Execution Logging">
    ```sql theme={null}
    simulation_runs
      id: "run_123"
      scenario_id: "scenario_2024_06_15_001"
      run_at: "2024-06-15T10:31:22Z"
      status: "completed"
      duration_ms: 1842
    ```
  </Step>

  <Step title="State Archival">
    ```sql theme={null}
    annual_trust_states
      simulation_run_id: "run_123"
      year: 2025
      cash_balance: 425000
      allocated_shares: 45000
      source_type: "simulated"
    ```
  </Step>
</Steps>

### Benefits

<CardGroup cols={2}>
  <Card title="Perfect Reproducibility" icon="repeat">
    Rerun any historical simulation and get identical results
  </Card>

  <Card title="Temporal Analysis" icon="clock">
    Compare how forecasts evolved over time
  </Card>

  <Card title="Audit Trail" icon="file-lines">
    Complete record of all modeling decisions
  </Card>

  <Card title="Debugging" icon="bug">
    Trace back to exact inputs that produced any output
  </Card>
</CardGroup>

### Real-World Application

```python theme={null}
# September 2024: Review June's forecast
june_run = engine.get_run("run_123")
sept_run = engine.get_run("run_456")

# Compare assumptions
diff = engine.compare_scenarios(
    june_run.scenario_id,
    sept_run.scenario_id
)

# Analyze: "Why did repurchase obligations increase?"
print(diff.changes)
# Output:
# - share_valuation.annual_growth_rate: 0.05 → 0.08
# - contribution_policy.amount: 500000 → 450000
```

***

## Principle 3: Abstraction

### The Agent Toolkit as a User Intent Layer

The engine is designed for deep integration with AI agents like Kelso (or Claude, GPT, etc.).

<Info>
  **First Principle:** The tools exposed to an agent represent high-level **user intents** (e.g., "compare two scenarios"), not a direct mapping to internal engine functions.
</Info>

### The Problem with Tight Coupling

```
❌ Tight Coupling:
   Agent Tool: get_share_pool()
   Engine Function: _calculate_share_pool_with_loan_releases()
   
   Problem: If engine refactors internal logic, agent breaks
```

### The Abstraction Layer

```
✅ Abstraction:
   Agent Tool: compare_scenarios(scenario_a, scenario_b)
   Intent: "User wants to understand differences"
   
   Engine: Can completely change internal implementation
   Result: Agent still works because intent is preserved
```

### Agent Toolkit Design

The toolkit exposes **user-facing intents**, not technical functions:

<Tabs>
  <Tab title="What Agents See">
    ```python theme={null}
    # High-level, stable intent-based API

    agent_toolkit = [
        "create_scenario",           # "I want to model a plan"
        "run_simulation",            # "Show me the forecast"
        "compare_scenarios",         # "How do these differ?"
        "analyze_repurchase_risk",   # "Where are the danger zones?"
        "optimize_contribution",     # "What's the ideal amount?"
        "export_results"             # "Give me a report"
    ]
    ```

    ☝️ *Stable, semantic, user-oriented*
  </Tab>

  <Tab title="What Engine Does">
    ```python theme={null}
    # Complex internal implementation (hidden from agents)

    def compare_scenarios(scenario_a_id, scenario_b_id):
        # 1. Load scenarios from database
        # 2. Run differential analysis
        # 3. Identify key drivers of differences
        # 4. Generate natural language summary
        # 5. Create visualization data
        # 6. Package for agent consumption
        
        # This can be completely rewritten without breaking agents
    ```

    ☝️ *Complex, technical, implementation-specific*
  </Tab>
</Tabs>

### Benefits

<AccordionGroup>
  <Accordion title="Stable Integration" icon="handshake">
    The agent's core conversational and analytical abilities remain intact even if the engine's internal logic is completely overhauled.
  </Accordion>

  <Accordion title="Natural Language Mapping" icon="comments">
    Agent tools map directly to how users think and speak:

    ```
    User: "Can you compare my June and September forecasts?"
    Agent: compare_scenarios("june_forecast", "sept_forecast")
    ```
  </Accordion>

  <Accordion title="Simplified Agent Development" icon="wand-magic-sparkles">
    Agent developers don't need deep knowledge of ESOP mechanics or engine internals. They work with high-level concepts that match user needs.
  </Accordion>
</AccordionGroup>

### Real-World Example

```
User: "Kelso, what happens if we reduce our contribution by 20%?"

Agent (Internal):
  1. create_scenario(base_scenario, modify={contribution: -20%})
  2. run_simulation(new_scenario)
  3. compare_scenarios(base_scenario, new_scenario)
  4. analyze_repurchase_risk(new_scenario)

Agent (Response):
  "If you reduce contributions by 20%, your 10-year repurchase 
   obligation increases by $1.2M due to slower loan paydown and 
   reduced cash reserves. Peak cash years shift from 2028 to 2030..."
```

***

## How These Principles Work Together

The three principles create a powerful, resilient system:

```
┌──────────────────────────────────────────────────────┐
│ Agent Layer (Abstraction)                            │
│ High-level user intents                              │
└─────────────────┬────────────────────────────────────┘
                  │
                  ↓
┌──────────────────────────────────────────────────────┐
│ Engine Layer (Separation of Concerns)                │
│ PlanRules + OperatingAssumptions → Processing        │
└─────────────────┬────────────────────────────────────┘
                  │
                  ↓
┌──────────────────────────────────────────────────────┐
│ Data Layer (Immutability)                            │
│ Versioned, append-only system of record              │
└──────────────────────────────────────────────────────┘
```

<Card title="The Compound Effect" icon="rocket">
  * **Separation** makes configuration intuitive
  * **Immutability** makes results reproducible
  * **Abstraction** makes integration stable

  → Result: A system that's both powerful and maintainable
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Simulation Core" icon="gears" href="/architecture/simulation-core">
    See how these principles are implemented in processing
  </Card>

  <Card title="Data Layer" icon="database" href="/architecture/data-layer">
    Explore the immutable database structure
  </Card>
</CardGroup>