aitbc/ai-memory/bug-patterns.md

# Bug Patterns — AITBC Repository

This document records known bug patterns and their fixes to prevent reoccurrence.

---

## Pattern: Service Import Name Shadowing in CLI

**Symptom**
```
KeyError: slice(None, 1, None)
```
or similar when invoking a CLI command that calls a service function.

**Root Cause**
CLI command modules import a service function (e.g., `generate_sar`) and then define a Click command function with the same name. The command function overwrites the imported service reference, causing the command body to call itself or the Click object instead of the service.

**Typical Code**
```python
from regulatory_reporting import generate_sar  # <-- import

@click.command()
def generate_sar(...):  # <-- name collision! Overwrites the import
    ...
    result = generate_sar(...)  # BAD: now refers to this function, not the service
```

**Fix**
Rename the imported function using an alias (e.g., `_svc` suffix) and update all internal calls.

```python
from regulatory_reporting import generate_sar as generate_sar_svc

@click.command()
def generate_sar(...):
    ...
    result = generate_sar_svc(...)  # GOOD: calls the actual service
```

**Files Affected**
- `cli/aitbc_cli/commands/regulatory.py` (primary example)

**Prevention**
- Use consistent import aliasing when names might clash.
- Consider naming CLI commands with a verb prefix (e.g., `cmd_generate_sar`) to avoid collision.
- Static analysis could flag functions that shadow imported names.

---

## Pattern: Missing Service Dependencies in CLI Venv

**Symptom**
```
ModuleNotFoundError: No module named 'numpy'
```
or similar when running CLI commands that import service modules.

**Root Cause**
CLI virtualenv lacks packages required by coordinator-api service modules (e.g., numpy, pandas, aiohttp, fastapi, uvicorn). The service modules are imported by CLI commands but their dependencies are not listed in the CLI's `pyproject.toml`.

**Fix**
Add the missing dependencies to the CLI package dependencies and reinstall.

```toml
dependencies = [
    # existing...
    "numpy>=1.26.0",
    "pandas>=2.0.0",
    "aiohttp>=3.9.0",
    "fastapi>=0.111.0",
    "uvicorn[standard]>=0.30.0"
]
```

Then:
```bash
pip install -e ./cli
```

**Files Affected**
- `pyproject.toml` (root)
- CLI virtualenv (`cli_venv/`)

**Prevention**
- Keep service module dependencies in a shared location or explicitly list them in CLI deps.
- Run import tests in CI to catch missing deps early.

---

## Pattern: Brother Chain Not Producing Blocks

**Symptom**
Chain height stays at 0, transactions (e.g., mintFaucet) not confirmed.

**Root Cause**
PoA proposer not defined as authority in the consensus configuration, or no node is acting as the authorized proposer.

**Fix**
Ensure the genesis configuration includes the proposer as an authority and that the node's `.env` matches:
- `PROPOSER_ID` and `PROPOSER_KEY` set
- `CHAIN_ID` matches the genesis file
- Node started with proper PYTHONPATH

If still not producing, check logs for authority registration and consider creating a manual block or restarting with a proper genesis that includes the proposer.

**Related Files**
- `apps/blockchain-node/src/aitbc_chain/consensus/poa.py`
- `.env` for brother node
- Genesis YAML file

**Prevention**
- Provide a helper script to initialize a PoA chain with a single proposer for devnets.
- Document the proposer setup clearly.

---

*End of bug patterns.*