> ## 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.

# Step 1: Initialization

> Calculate share price and prepare for annual processing

## Overview

Step 1 initializes the annual processing cycle by calculating the current share price and preparing all state variables for the year's simulation.

<Info>
  This is the **foundation step** that establishes share valuations used throughout all subsequent steps.
</Info>

## Core Responsibilities

<CardGroup cols={2}>
  <Card title="Share Price Calculation" icon="dollar-sign">
    Calculate per-share value from company equity and outstanding shares
  </Card>

  <Card title="Multi-Class Support" icon="shapes">
    Initialize security-specific prices and aggregate metrics
  </Card>

  <Card title="Growth Application" icon="chart-line">
    Apply annual growth rate to company equity value
  </Card>
</CardGroup>

***

## Processing Logic

### Single-Class Mode

The simplest calculation:

```python theme={null}
# Calculate share price from company equity
share_price = company_equity_value / total_outstanding_shares

# Example:
# Company Equity: $50,000,000
# Outstanding Shares: 100,000
# Share Price: $50,000,000 / 100,000 = $500.00/share
```

### Multi-Class Mode

When multiple securities exist, Step 1:

<Steps>
  <Step title="Initialize Security Prices">
    Set each security's price from its FMV or use company aggregate price as fallback
  </Step>

  <Step title="Calculate Aggregate Equity">
    Sum equity value across all securities:

    ```python theme={null}
    equity_total = sum(
        security.current_share_price * security.total_outstanding_shares
        for security in securities.values()
    )
    ```
  </Step>

  <Step title="Set Aggregate Share Price">
    For legacy compatibility:

    ```python theme={null}
    company_share_price = equity_total / total_outstanding_shares
    ```
  </Step>

  <Step title="Initialize Carry-Over Pools">
    Set up per-security recycled and forfeited share pools
  </Step>
</Steps>

**Example Multi-Class Calculation:**

```python theme={null}
# Class A: 60,000 shares at $600/share = $36,000,000
# Class B: 40,000 shares at $400/share = $16,000,000
# Total Equity: $52,000,000
# Aggregate Price: $52,000,000 / 100,000 = $520/share
```

***

## Growth Application

After initializing prices, Step 1 applies the annual growth rate:

<Tabs>
  <Tab title="Single-Class">
    ```python theme={null}
    growth_rate = 1 + share_price_growth_rate  # e.g., 1.05 for 5%
    company_equity_value *= growth_rate

    # Example:
    # Beginning Equity: $50,000,000
    # Growth Rate: 5% (1.05)
    # Ending Equity: $50,000,000 * 1.05 = $52,500,000
    # New Share Price: $52,500,000 / 100,000 = $525/share
    ```
  </Tab>

  <Tab title="Multi-Class">
    Growth is applied **uniformly across all securities**:

    ```python theme={null}
    growth_rate = 1 + share_price_growth_rate

    for security in securities.values():
        security.current_share_price *= growth_rate

    # Recalculate aggregate equity
    equity_total = sum(
        security.current_share_price * security.total_outstanding_shares
        for security in securities.values()
    )

    company_equity_value = equity_total
    ```

    **Example:**

    * Class A: $600 * 1.05 = $630/share
    * Class B: $400 * 1.05 = $420/share
    * New aggregate: ($630 * 60,000) + ($420 \* 40,000) = \$54,600,000
  </Tab>
</Tabs>

<Warning>
  Growth is applied to **equity value**, not share count. Outstanding shares remain constant unless modified by redemptions in Step 7.
</Warning>

***

***

## Compliance Events

Step 1 emits two compliance events:

<Tabs>
  <Tab title="share_price_calculated">
    Initial price before growth:

    ```json theme={null}
    {
      "year": 2025,
      "phase": "initialization",
      "event": "share_price_calculated",
      "details": {
        "share_price": 500.00,
        "equity_value": 50000000.00,
        "outstanding_shares": 100000.0
      }
    }
    ```
  </Tab>

  <Tab title="share_price_initialized">
    Price after applying growth:

    ```json theme={null}
    {
      "year": 2025,
      "phase": "init",
      "event": "share_price_initialized",
      "details": {
        "growth_applied": 1.05,
        "new_equity_value": 52500000.00
      }
    }
    ```
  </Tab>

  <Tab title="share_price_computed (structured)">
    Complete audit trail:

    ```json theme={null}
    {
      "year": 2025,
      "phase": "init",
      "event": "share_price_computed",
      "entity_type": "company",
      "entity_id": null,
      "inputs": {
        "equity_value": 50000000.00,
        "outstanding_shares": 100000.0,
        "share_price_growth_rate": 0.05
      },
      "outputs": {
        "share_price": 525.00,
        "new_equity_value": 52500000.00
      }
    }
    ```
  </Tab>
</Tabs>

***

## Data Flow

### Inputs

<Tabs>
  <Tab title="Company State">
    ```python theme={null}
    {
      "company_equity_value": 50000000.00,  # Total company value
      "total_outstanding_shares": 100000.0, # Shares in circulation
      "securities": {                        # Multi-class mode only
        "CLASS_A": {
          "security_id": "CLASS_A",
          "initial_fair_market_value": 600.00,
          "total_outstanding_shares": 60000.0,
          "initial_recycled_shares": 500.0,
          "initial_forfeited_shares": 150.0
        },
        "CLASS_B": {...}
      }
    }
    ```
  </Tab>

  <Tab title="Financial Assumptions">
    ```python theme={null}
    {
      "share_price_growth_rate": 0.05  # 5% annual growth
    }
    ```
  </Tab>
</Tabs>

### Outputs

<Tabs>
  <Tab title="Company State (Updated)">
    ```python theme={null}
    {
      "current_share_price": 525.00,         # New price after growth
      "company_equity_value": 52500000.00,   # New equity after growth
      "securities": {                         # Multi-class mode
        "CLASS_A": {
          "current_share_price": 630.00     # Grown price
        },
        "CLASS_B": {
          "current_share_price": 420.00     # Grown price
        }
      }
    }
    ```
  </Tab>

  <Tab title="Carry-Over State">
    ```python theme={null}
    {
      "recycled_shares_by_security": {       # Multi-class mode
        "CLASS_A": 500.0,
        "CLASS_B": 0.0
      },
      "forfeited_shares_next_year_by_security": {
        "CLASS_A": 150.0,
        "CLASS_B": 0.0
      }
    }
    ```
  </Tab>
</Tabs>

***

## Implementation Notes

### Division by Zero Protection

```python theme={null}
# If no shares outstanding, use default denominator
denominator = total_outstanding_shares if total_outstanding_shares > 0 else Decimal("1")
share_price = company_equity_value / denominator
```

### Precision Handling

All financial calculations use `Decimal` type to avoid floating-point errors:

```python theme={null}
from decimal import Decimal

growth_rate = Decimal(str(1 + share_price_growth_rate))
company_equity_value *= growth_rate
```

***

## Related Steps

<CardGroup cols={2}>
  <Card title="Step 2: Share Pool" icon="shapes" href="/simulation/step-2-share-pool">
    Uses share price to value loan releases and contributions
  </Card>

  <Card title="Step 3: Allocation" icon="divide" href="/simulation/step-3-allocation">
    Uses share price to enforce ERISA annual addition caps
  </Card>

  <Card title="Step 8: Year End" icon="flag-checkered" href="/simulation/step-8-year-end">
    Reconciles TrustCashLedger balances
  </Card>

  <Card title="Company State" icon="building" href="/models/esop-trust">
    Data model for company equity and shares
  </Card>
</CardGroup>

***

## Timing Note

<Info>
  **Important:** Yearly evolution of employee data (age, service years, compensation growth) happens in **Step 8**, not Step 1.

  Step 1 focuses solely on share price and company-level state initialization.
</Info>

***

## Example Scenario

**Setup:**

* Company Equity: \$50M
* Outstanding Shares: 100,000
* Growth Rate: 5%
* Multi-class: Class A (60K shares), Class B (40K shares)

**Processing:**

```python theme={null}
# 1. Initialize Class A
CLASS_A.current_share_price = 600.00
CLASS_A_equity = 600.00 * 60,000 = $36,000,000

# 2. Initialize Class B
CLASS_B.current_share_price = 400.00
CLASS_B_equity = 400.00 * 40,000 = $16,000,000

# 3. Calculate aggregate
company_equity_value = $36M + $16M = $52M
company_share_price = $52M / 100,000 = $520/share

# 4. Apply growth (5%)
CLASS_A.current_share_price = 600.00 * 1.05 = $630.00
CLASS_B.current_share_price = 400.00 * 1.05 = $420.00

# 5. Recalculate aggregate
company_equity_value = (630 * 60K) + (420 * 40K) = $54.6M
company_share_price = $54.6M / 100,000 = $546/share

# (Removed OIA BOY setup in v0.3)
```

**Result:**

* ✅ Share prices calculated and grown
* ✅ Aggregate metrics updated
* ✅ Ready for Step 2

***

## Summary

Step 1 is a **foundational initialization step** that:

* ✅ Calculates share price from company equity
* ✅ Supports both single-class and multi-class modes
* ✅ Applies annual growth rate
* ✅ Sets up per-security carry-over pools
* ✅ Emits comprehensive compliance events

This step establishes the **pricing basis** used throughout all subsequent steps in the annual cycle.