Step 1: Initialization

Overview

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

This is the foundation step that establishes share valuations used throughout all subsequent steps.

Core Responsibilities

Share Price Calculation

Calculate per-share value from company equity and outstanding shares

Multi-Class Support

Initialize security-specific prices and aggregate metrics

Growth Application

Apply annual growth rate to company equity value

Processing Logic

Single-Class Mode

The simplest calculation:

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

Initialize Security Prices

Set each security’s price from its FMV or use company aggregate price as fallback

Calculate Aggregate Equity

Sum equity value across all securities:

equity_total = sum(
    security.current_share_price * security.total_outstanding_shares
    for security in securities.values()
)

Set Aggregate Share Price

For legacy compatibility:

company_share_price = equity_total / total_outstanding_shares

Initialize Carry-Over Pools

Set up per-security recycled and forfeited share pools

Example Multi-Class Calculation:

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

Single-Class
Multi-Class

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

Growth is applied uniformly across all securities:

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

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

Compliance Events

Step 1 emits two compliance events:

share_price_calculated
share_price_initialized
share_price_computed (structured)

Initial price before growth:

{
  "year": 2025,
  "phase": "initialization",
  "event": "share_price_calculated",
  "details": {
    "share_price": 500.00,
    "equity_value": 50000000.00,
    "outstanding_shares": 100000.0
  }
}

Complete audit trail:

{
  "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
  }
}

Data Flow

Inputs

Company State
Financial Assumptions

{
  "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": {...}
  }
}

{
  "share_price_growth_rate": 0.05  # 5% annual growth
}

Outputs

Company State (Updated)
Carry-Over State

{
  "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
    }
  }
}

{
  "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
  }
}

Implementation Notes

Division by Zero Protection

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

from decimal import Decimal

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

Step 2: Share Pool

Uses share price to value loan releases and contributions

Step 3: Allocation

Uses share price to enforce ERISA annual addition caps

Step 8: Year End

Reconciles TrustCashLedger balances

Company State

Data model for company equity and shares

Timing Note

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.

Example Scenario

Setup:

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

Processing:

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

Getting Started

Configuration Guide

For Enterprise

Architecture

Data Models

Simulation Pipeline

Examples

API Reference

API Schemas

Overview

Core Responsibilities

Share Price Calculation

Multi-Class Support

Growth Application

Processing Logic

Single-Class Mode

Multi-Class Mode

Growth Application

Compliance Events

Data Flow

Inputs

Outputs

Implementation Notes

Division by Zero Protection

Precision Handling

Step 2: Share Pool

Step 3: Allocation

Step 8: Year End

Company State

Timing Note

Example Scenario

Summary

​Overview

​Core Responsibilities

Share Price Calculation

Multi-Class Support

Growth Application

​Processing Logic

​Single-Class Mode

​Multi-Class Mode

​Growth Application

​Compliance Events

​Data Flow

​Inputs

​Outputs

​Implementation Notes

​Division by Zero Protection

​Precision Handling

​Related Steps

Step 2: Share Pool

Step 3: Allocation

Step 8: Year End

Company State

​Timing Note

​Example Scenario

​Summary

Overview

Core Responsibilities

Processing Logic

Single-Class Mode

Multi-Class Mode

Growth Application

Compliance Events

Data Flow

Inputs

Outputs

Implementation Notes

Division by Zero Protection

Precision Handling

Related Steps

Timing Note

Example Scenario

Summary