# State Database - Runtime Mutable Variables

**Purpose**: FP-compliant replacement for mutable global variables.

## What This Is

This directory contains a lightweight SQLite database for managing runtime mutable state in a functional programming context. Instead of using mutable global variables (which violate FP principles), use this database-backed state management.

## Why This Exists

In FP, functions should be pure (no side effects, no hidden state). However, real applications need mutable state (counters, toggles, runtime config). This database provides **explicit, traceable state mutations** while maintaining FP compliance.

## Usage

Import the state operations module in your source files:

```python
from .state import state_operations as state

# Set a variable
result = state.set_var('counter', 0)

# Get a variable
result = state.get_var('counter')
if result.success:
    print(f"Counter: {result.data}")

# Increment (common for counters)
result = state.increment_var('counter', 1)

# Delete a variable
result = state.delete_var('counter')
```

## Files

- **state_operations.py**: Template CRUD helper functions (adapt to project language)
- **README.md**: This file

The database is created by the `create_state_database` helper using the SQL schema
at `src/aimfp/database/initialization/state_db.sql`. The binary `runtime.db` is NOT
shipped as a template — it is created from SQL at runtime.

## Schema

See `src/aimfp/database/initialization/state_db.sql` for the authoritative schema.
Summary:

```sql
CREATE TABLE variables (
    var_name TEXT PRIMARY KEY,
    var_value TEXT NOT NULL,
    var_type TEXT CHECK(var_type IN ('int', 'float', 'str', 'bool', 'dict', 'list')),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

## When to Use

- ✅ Replacing mutable global variables (`global counter`)
- ✅ Runtime configuration that changes during execution
- ✅ Application state that needs to persist across function calls
- ✅ Counters, toggles, flags

## When NOT to Use

- ❌ Session management (create separate database)
- ❌ User data storage (use application database)
- ❌ Rate limiting (create separate database)
- ❌ Job queues (create separate database)

## Extending

You can add tables to this database for additional state needs. AI can help extend the schema and operations as required.

---

**Generated by AIMFP** during project initialization.
