# Design Document — Trading Feedback Engine

## Overview

This design adds a periodic trading performance reporting system to Stonks Oracle. The system collects trading data (P&L, recommendations, positions, risk metrics, model quality), generates structured JSON reports with AI-powered summaries, validates report metrics against live data, and stores reports for retrieval via API.

The core challenge is fitting AI summarization within the 8k-token context window of the `qwen3.5:9b-fast` model on the local Ollama instance. The design addresses this with a chunking strategy that serializes report section data into ≤6,000-character chunks, summarizes each chunk independently, then merges chunk summaries into a final section summary. This hierarchical summarization approach keeps each LLM call well within the token budget while producing coherent narratives.

### Design Rationale

A trading system without periodic performance feedback forces the operator to manually query tables and compute metrics. The feedback engine closes this gap by:

1. **Automating data collection** — pulling from 7+ tables (trading_decisions, orders, positions, portfolio_snapshots, recommendations, prediction_outcomes, model_metric_snapshots) into a single structured report
2. **AI-powered summarization** — using the existing agent infrastructure (ai_agents, AgentConfigResolver, llm_factory) to generate natural-language summaries that highlight trends and anomalies
3. **Cross-validation** — comparing computed metrics against live validation data (prediction_outcomes, model_metric_snapshots) and flagging discrepancies >5%
4. **Persistent storage** — storing reports as JSONB for historical comparison and trend analysis
5. **Scheduled generation** — daily (after market close) and weekly (Saturday) reports via Redis queue jobs

The design reuses existing infrastructure: asyncpg for persistence, FastAPI for API endpoints, Redis queues for async job processing, the ai_agents/AgentConfigResolver/llm_factory stack for LLM access, and TanStack Query hooks on the frontend.

---

## Architecture

### High-Level Data Flow

```mermaid
flowchart TD
    subgraph "Scheduling (Trigger)"
        A[Scheduler Service] -->|after 16:30 ET daily| B[Redis Queue<br/>stonks:queue:report_generation]
        A -->|Saturday weekly| B
        C[Manual API Trigger] --> B
    end

    subgraph "Report Generation (Async Worker)"
        B --> D[Report Generator<br/>services/reporting/generator.py]
        D -->|1. Collect| E[Data Collector<br/>services/reporting/collector.py]
        E -->|queries| F[(trading_decisions<br/>orders, positions<br/>portfolio_snapshots<br/>recommendations)]
        D -->|2. Build sections| G[Section Builder<br/>services/reporting/sections.py]
        G -->|P&L, accuracy,<br/>positions, risk,<br/>model quality| H[Report Sections]
        D -->|3. Validate| I[Report Validator<br/>services/reporting/validator.py]
        I -->|cross-check| J[(prediction_outcomes<br/>model_metric_snapshots)]
        D -->|4. Summarize| K[AI Summarizer<br/>services/reporting/summarizer.py]
        K -->|chunk & summarize| L[Report_Summarizer_Agent<br/>via AgentConfigResolver<br/>+ llm_factory]
        D -->|5. Store| M[(trading_reports table)]
    end

    subgraph "API Layer"
        N[GET /api/reports] -->|paginated list| M
        O[GET /api/reports/:id] -->|full report| M
    end

    subgraph "Frontend"
        P[useReports hook] --> N
        Q[useReport hook] --> O
    end
```

### Scheduling Strategy

| Component | Trigger | Cadence |
|-----------|---------|---------|
| Daily Report | Scheduler after 16:30 ET | Every trading day |
| Weekly Report | Scheduler on Saturday | Weekly (Mon–Fri coverage) |
| Report Generator Worker | Redis queue consumer | On-demand from queue |
| AI Summarizer | Called by generator | Per report section |

### Chunking Strategy

The `qwen3.5:9b-fast` model has an 8k-token context window. With the system prompt (~200 tokens) and response budget (~200 tokens), roughly 7,600 tokens remain for input. At ~4 chars/token for structured data, that's ~30,400 characters. The 6,000-character chunk limit provides a 5x safety margin to account for JSON overhead, prompt framing, and tokenization variance.

```mermaid
flowchart LR
    A[Section Data<br/>e.g. 15,000 chars] --> B{> 6,000 chars?}
    B -->|No| C[Single LLM call<br/>→ summary]
    B -->|Yes| D[Split into chunks<br/>≤ 6,000 chars each]
    D --> E[Chunk 1 → LLM → summary 1]
    D --> F[Chunk 2 → LLM → summary 2]
    D --> G[Chunk N → LLM → summary N]
    E --> H[Merge summaries<br/>→ final LLM call<br/>→ section summary]
    F --> H
    G --> H
```

---

## Components and Interfaces

### New Modules

| Module | File | Responsibility |
|--------|------|----------------|
| Report Data Collector | `services/reporting/collector.py` | Queries trading data for a reporting period |
| Report Section Builder | `services/reporting/sections.py` | Builds structured report sections from raw data |
| Report Validator | `services/reporting/validator.py` | Cross-checks metrics against validation tables |
| AI Summarizer | `services/reporting/summarizer.py` | Chunks data and generates AI summaries |
| Report Generator | `services/reporting/generator.py` | Orchestrates the full report generation pipeline |
| Report Models | `services/reporting/models.py` | Pydantic models for report structure and serialization |

### Modified Modules

| Module | File | Changes |
|--------|------|---------|
| Query API | `services/api/app.py` | 2 new `/api/reports` endpoints |
| Redis Keys | `services/shared/redis_keys.py` | New `QUEUE_REPORT_GENERATION` constant |
| Frontend Hooks | `frontend/src/api/hooks.ts` | 2 new report hooks |
| DB Migration | `infra/migrations/038_trading_reports.sql` | New table + agent seed |

### Component Interface Details

#### 1. Report Models (`services/reporting/models.py`)

```python
from __future__ import annotations
from datetime import date, datetime
from enum import Enum
from typing import Optional
from pydantic import BaseModel, Field


class ReportType(str, Enum):
    DAILY = "daily"
    WEEKLY = "weekly"


class ValidationStatus(str, Enum):
    PASSED = "passed"
    WARNINGS = "warnings"


class ValidationWarning(BaseModel):
    field_name: str
    computed_value: float
    snapshot_value: float
    pct_difference: float


class PLSection(BaseModel):
    realized_pnl: float
    unrealized_pnl: float
    daily_return: float
    cumulative_return: float
    win_count: int
    loss_count: int
    win_rate: float
    profit_factor: float
    sharpe_ratio: float
    summary: str = ""
    validation_warnings: list[ValidationWarning] = Field(default_factory=list)


class RecommendationAccuracySection(BaseModel):
    total_evaluated: int
    act_count: int
    skip_count: int
    acted_win_rate: float
    avg_confidence_acted: float
    avg_confidence_skipped: float
    summary: str = ""
    validation_warnings: list[ValidationWarning] = Field(default_factory=list)


class PositionDetail(BaseModel):
    ticker: str
    entry_price: float
    current_or_exit_price: float
    pnl: float
    pnl_pct: float
    hold_duration_hours: float
    status: str  # "open" or "closed"


class PositionPerformanceSection(BaseModel):
    positions: list[PositionDetail] = Field(default_factory=list)
    summary: str = ""


class RiskMetricsSection(BaseModel):
    current_risk_tier: str
    portfolio_heat: float
    max_drawdown: float
    current_drawdown_pct: float
    reserve_pool_balance: float
    circuit_breaker_event_count: int
    summary: str = ""


class ModelQualityWindow(BaseModel):
    lookback: str
    win_rate: float | None
    directional_accuracy: float | None
    information_coefficient: float | None
    calibration_error: float | None
    brier_score: float | None


class ModelQualitySection(BaseModel):
    windows: list[ModelQualityWindow] = Field(default_factory=list)
    summary: str = ""
    validation_warnings: list[ValidationWarning] = Field(default_factory=list)


class ReportData(BaseModel):
    """Top-level report structure stored as JSONB."""
    pnl: PLSection
    recommendation_accuracy: RecommendationAccuracySection
    position_performance: PositionPerformanceSection
    risk_metrics: RiskMetricsSection
    model_quality: ModelQualitySection
    executive_summary: str = ""
    validation_status: ValidationStatus = ValidationStatus.PASSED
    generated_at: datetime
    period_start: date
    period_end: date
    report_type: ReportType
```

#### 2. Report Data Collector (`services/reporting/collector.py`)

```python
from __future__ import annotations
from dataclasses import dataclass
from datetime import date, datetime
import asyncpg


@dataclass
class CollectedData:
    """Raw data collected for a reporting period."""
    trading_decisions: list[dict]
    orders: list[dict]
    open_positions: list[dict]
    closed_positions: list[dict]
    portfolio_snapshot: dict | None
    previous_portfolio_snapshot: dict | None
    recommendations: list[dict]
    prediction_outcomes: list[dict]
    model_metric_snapshots: list[dict]
    circuit_breaker_events: list[dict]
    reserve_pool_balance: float


async def collect_report_data(
    pool: asyncpg.Pool,
    period_start: date,
    period_end: date,
) -> CollectedData:
    """Query all trading data for the reporting period.

    Queries: trading_decisions, orders, positions, portfolio_snapshots,
    recommendations, prediction_outcomes, model_metric_snapshots,
    circuit_breaker_events, reserve_pool_ledger.

    Returns CollectedData with all raw query results.
    If no trading_decisions exist, returns empty lists (zero-activity).
    """
    ...
```

#### 3. Report Section Builder (`services/reporting/sections.py`)

```python
from __future__ import annotations
from services.reporting.models import (
    PLSection, RecommendationAccuracySection,
    PositionPerformanceSection, PositionDetail,
    RiskMetricsSection, ModelQualitySection, ModelQualityWindow,
)
from services.reporting.collector import CollectedData


def build_pnl_section(data: CollectedData) -> PLSection:
    """Build P&L section from collected data.

    Computes realized/unrealized P&L, daily return, cumulative return,
    win/loss counts, win rate, profit factor, and Sharpe ratio from
    portfolio_snapshot and closed positions.
    """
    ...


def build_recommendation_accuracy_section(data: CollectedData) -> RecommendationAccuracySection:
    """Build recommendation accuracy section.

    Joins trading_decisions with prediction_outcomes to compute
    act/skip breakdown, win rate of acted recommendations, and
    average confidence of acted vs skipped.
    """
    ...


def build_position_performance_section(data: CollectedData) -> PositionPerformanceSection:
    """Build position performance section.

    Lists each position (open and closed) with entry price,
    current/exit price, P&L, P&L%, and hold duration.
    """
    ...


def build_risk_metrics_section(data: CollectedData) -> RiskMetricsSection:
    """Build risk metrics section.

    Extracts current risk tier, portfolio heat, max drawdown,
    current drawdown %, reserve pool balance, and circuit breaker
    event count from collected data.
    """
    ...


def build_model_quality_section(data: CollectedData) -> ModelQualitySection:
    """Build model quality section.

    Extracts latest model_metric_snapshot values for 7d, 30d, 90d
    lookback windows.
    """
    ...
```

#### 4. Report Validator (`services/reporting/validator.py`)

```python
from __future__ import annotations
import asyncpg
from services.reporting.models import (
    ReportData, ValidationStatus, ValidationWarning,
)


DISCREPANCY_THRESHOLD_PCT = 5.0


def validate_recommendation_accuracy(
    section: "RecommendationAccuracySection",
    prediction_outcomes: list[dict],
) -> list[ValidationWarning]:
    """Cross-reference reported win rates with prediction_outcomes.

    Compares computed win rate against direction_correct/profitable
    fields from prediction_outcomes for the same tickers and period.
    Returns warnings for discrepancies > 5%.
    """
    ...


def validate_model_quality(
    section: "ModelQualitySection",
    metric_snapshots: list[dict],
) -> list[ValidationWarning]:
    """Compare reported model quality metrics against model_metric_snapshots.

    Flags discrepancies > 5% between computed and snapshot values
    for win_rate, directional_accuracy, IC, ECE, and Brier score.
    """
    ...


def compute_validation_status(report: ReportData) -> ValidationStatus:
    """Determine overall validation status.

    Returns 'passed' if no warnings across all sections,
    'warnings' if any section has validation warnings.
    """
    ...
```

#### 5. AI Summarizer (`services/reporting/summarizer.py`)

```python
from __future__ import annotations
import asyncpg
from services.shared.agent_config import AgentConfigResolver


CHUNK_SIZE_LIMIT = 6000  # characters per chunk
MAX_SUMMARY_WORDS = 200  # per section summary
MAX_EXECUTIVE_SUMMARY_WORDS = 300


def chunk_data(serialized: str, max_chars: int = CHUNK_SIZE_LIMIT) -> list[str]:
    """Split serialized data into chunks of at most max_chars.

    Splits on newline boundaries to avoid breaking JSON structures.
    Each chunk is ≤ max_chars characters.
    Returns at least one chunk (even if empty input).
    """
    ...


async def summarize_section(
    pool: asyncpg.Pool,
    resolver: AgentConfigResolver,
    section_name: str,
    section_data: str,
) -> str:
    """Generate AI summary for a report section.

    1. Serialize section data to string
    2. Chunk if > CHUNK_SIZE_LIMIT
    3. Summarize each chunk via Report_Summarizer_Agent
    4. If multiple chunks, merge summaries with a final LLM call
    5. Log each invocation to agent_performance_log
    6. On failure after max_retries, fall back to deterministic summary

    Uses AgentConfigResolver to resolve agent config by slug
    'report-summarizer', then llm_factory to build the LLM client.
    """
    ...


def build_deterministic_summary(section_name: str, section_data: dict) -> str:
    """Build a fallback deterministic summary from raw metrics.

    Produces a template-based text summary when AI summarization fails.
    """
    ...


async def generate_executive_summary(
    pool: asyncpg.Pool,
    resolver: AgentConfigResolver,
    section_summaries: dict[str, str],
) -> str:
    """Generate executive summary from all section summaries.

    Concatenates section summaries, chunks if needed, and produces
    a ≤300-word synthesis via the Report_Summarizer_Agent.
    Falls back to concatenated section summaries on failure.
    """
    ...
```

#### 6. Report Generator (`services/reporting/generator.py`)

```python
from __future__ import annotations
from datetime import date
import asyncpg
from services.reporting.models import ReportData, ReportType


async def generate_report(
    pool: asyncpg.Pool,
    report_type: ReportType,
    period_start: date,
    period_end: date,
) -> ReportData:
    """Orchestrate full report generation.

    1. Collect data via collector
    2. Build sections via section builder
    3. Validate sections via validator
    4. Generate AI summaries via summarizer
    5. Generate executive summary
    6. Assemble final ReportData
    """
    ...


async def store_report(
    pool: asyncpg.Pool,
    report: ReportData,
) -> str:
    """Store report in trading_reports table.

    Uses INSERT ... ON CONFLICT (report_type, period_start, period_end)
    DO UPDATE to handle regeneration of existing reports.

    Returns the report UUID.
    """
    ...


async def process_report_job(
    pool: asyncpg.Pool,
    job: dict,
) -> None:
    """Process a report generation job from the Redis queue.

    Deserializes job payload, calls generate_report + store_report.
    Handles retries with exponential backoff (up to 3 attempts).
    Rejects duplicate jobs for the same report_type + period.
    """
    ...
```

#### 7. API Endpoints (added to `services/api/app.py`)

| Endpoint | Method | Parameters | Returns |
|----------|--------|------------|---------|
| `GET /api/reports` | GET | `report_type`, `start_date`, `end_date`, `limit`, `offset` | Paginated list: id, report_type, period_start, period_end, validation_status, generated_at |
| `GET /api/reports/{report_id}` | GET | — | Full report including report_data JSONB |

#### 8. Frontend Hooks (added to `frontend/src/api/hooks.ts`)

```typescript
export interface ReportListItem {
  id: string;
  report_type: string;
  period_start: string;
  period_end: string;
  validation_status: string;
  generated_at: string;
}

export interface ReportDetail extends ReportListItem {
  report_data: Record<string, unknown>;
  created_at: string;
}

export function useReports(params?: {
  report_type?: string;
  start_date?: string;
  end_date?: string;
  limit?: number;
  offset?: number;
}) {
  const qs = new URLSearchParams();
  if (params?.report_type) qs.set('report_type', params.report_type);
  if (params?.start_date) qs.set('start_date', params.start_date);
  if (params?.end_date) qs.set('end_date', params.end_date);
  if (params?.limit) qs.set('limit', String(params.limit));
  if (params?.offset) qs.set('offset', String(params.offset));
  const path = `/api/reports${qs.toString() ? '?' + qs : ''}`;
  return useGet<ReportListItem[]>(['reports', params], 'query', path);
}

export function useReport(id: string | undefined) {
  return useGet<ReportDetail>(
    ['report', id], 'query', `/api/reports/${id}`, !!id
  );
}
```

---

## Data Models

### Database Schema (Migration 038)

#### trading_reports

```sql
CREATE TABLE IF NOT EXISTS trading_reports (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    report_type VARCHAR(20) NOT NULL,
    period_start DATE NOT NULL,
    period_end DATE NOT NULL,
    report_data JSONB NOT NULL,
    validation_status VARCHAR(20) NOT NULL DEFAULT 'passed',
    generated_at TIMESTAMPTZ NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT uq_trading_reports_period UNIQUE (report_type, period_start, period_end),
    CONSTRAINT chk_report_type CHECK (report_type IN ('daily', 'weekly'))
);

CREATE INDEX IF NOT EXISTS idx_trading_reports_type ON trading_reports(report_type);
CREATE INDEX IF NOT EXISTS idx_trading_reports_period ON trading_reports(period_start, period_end);
CREATE INDEX IF NOT EXISTS idx_trading_reports_generated ON trading_reports(generated_at DESC);
```

#### Report Summarizer Agent Seed

```sql
INSERT INTO ai_agents (name, slug, purpose, model_provider, model_name, system_prompt, prompt_version, schema_version, temperature, max_tokens, timeout_seconds, max_retries, source)
SELECT * FROM (VALUES
    (
        'Report Summarizer',
        'report-summarizer',
        'Generates concise natural-language summaries of trading performance report sections. Processes chunked data within the 8k-token context window.',
        'ollama',
        'qwen3.5:9b-fast',
        E'You are a concise financial performance analyst. You summarize trading performance data into clear, professional prose.\n\nSTRICT RULES:\n1. Do NOT fabricate any data not present in the input.\n2. Do NOT add opinions, predictions, or recommendations.\n3. Keep each summary under 200 words.\n4. Highlight notable trends, outliers, and changes from prior periods.\n5. Use precise numbers from the input data.\n6. Use a neutral, professional tone.\n7. Return ONLY the summary text. No JSON, no markdown, no commentary.',
        'report-summarizer-v1',
        '1.0.0',
        0.0,
        1024,
        60,
        2,
        'system'
    )
) AS v(name, slug, purpose, model_provider, model_name, system_prompt, prompt_version, schema_version, temperature, max_tokens, timeout_seconds, max_retries, source)
WHERE NOT EXISTS (SELECT 1 FROM ai_agents WHERE slug = 'report-summarizer');
```

### Report JSONB Structure

The `report_data` column stores a JSON object matching the `ReportData` Pydantic model:

```json
{
  "pnl": {
    "realized_pnl": 125.50,
    "unrealized_pnl": -30.20,
    "daily_return": 0.012,
    "cumulative_return": 0.085,
    "win_count": 8,
    "loss_count": 3,
    "win_rate": 0.727,
    "profit_factor": 2.15,
    "sharpe_ratio": 1.42,
    "summary": "AI-generated summary...",
    "validation_warnings": []
  },
  "recommendation_accuracy": {
    "total_evaluated": 15,
    "act_count": 8,
    "skip_count": 7,
    "acted_win_rate": 0.75,
    "avg_confidence_acted": 0.72,
    "avg_confidence_skipped": 0.48,
    "summary": "AI-generated summary...",
    "validation_warnings": []
  },
  "position_performance": {
    "positions": [
      {
        "ticker": "AAPL",
        "entry_price": 185.50,
        "current_or_exit_price": 192.30,
        "pnl": 68.00,
        "pnl_pct": 3.66,
        "hold_duration_hours": 72.5,
        "status": "open"
      }
    ],
    "summary": "AI-generated summary..."
  },
  "risk_metrics": {
    "current_risk_tier": "moderate",
    "portfolio_heat": 0.12,
    "max_drawdown": 0.08,
    "current_drawdown_pct": 0.03,
    "reserve_pool_balance": 450.00,
    "circuit_breaker_event_count": 1,
    "summary": "AI-generated summary..."
  },
  "model_quality": {
    "windows": [
      {
        "lookback": "7d",
        "win_rate": 0.65,
        "directional_accuracy": 0.62,
        "information_coefficient": 0.08,
        "calibration_error": 0.12,
        "brier_score": 0.22
      }
    ],
    "summary": "AI-generated summary...",
    "validation_warnings": []
  },
  "executive_summary": "AI-generated executive summary...",
  "validation_status": "passed",
  "generated_at": "2025-01-15T21:30:00Z",
  "period_start": "2025-01-15",
  "period_end": "2025-01-15",
  "report_type": "daily"
}
```


---

## Correctness Properties

*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*

The following properties were derived from the acceptance criteria through systematic prework analysis. After reflection, 5 unique properties remain. Report section structure checks (3.1–3.5) are subsumed by the round-trip property — if a ReportData object survives serialization and deserialization, its structure is correct by construction (Pydantic enforces required fields). Validation status computation (4.4) is subsumed by the discrepancy detection property. ISO 8601 datetime formatting (8.4) is verified as part of the round-trip property since Pydantic's JSON serialization uses ISO 8601 by default and the round-trip would fail if datetimes were mangled.

### Property 1: Chunking Round-Trip and Size Constraint

*For any* input string, splitting it into chunks with a maximum size limit SHALL produce chunks where (a) every chunk is ≤ the size limit in characters, (b) no chunk is empty (except when the input itself is empty, which produces exactly one empty chunk), and (c) concatenating all chunks in order reconstructs the original input string.

**Validates: Requirements 2.2**

### Property 2: Report Serialization Round-Trip

*For any* valid ReportData object (with valid P&L, recommendation accuracy, position performance, risk metrics, and model quality sections), serializing to JSON and then deserializing back SHALL produce a ReportData object equivalent to the original. All datetime fields in the serialized JSON SHALL be in ISO 8601 format.

**Validates: Requirements 8.1, 8.2, 8.3, 8.4**

### Property 3: Validation Discrepancy Detection Correctness

*For any* pair of computed metric value and snapshot metric value (both finite, non-negative floats), the validation function SHALL produce a warning if and only if the percentage difference exceeds 5%. The percentage difference SHALL be computed as `|computed - snapshot| / snapshot * 100` when snapshot > 0, and SHALL flag any non-zero computed value when snapshot is 0.

**Validates: Requirements 4.1, 4.2, 4.3, 4.4**

### Property 4: Recommendation Accuracy Aggregation

*For any* non-empty list of trading decisions with associated prediction outcomes (each having a boolean `direction_correct`, boolean `profitable`, and float `excess_return_vs_spy`), the computed win rate SHALL equal the count of profitable outcomes divided by total outcomes, the directional accuracy SHALL equal the count of direction-correct outcomes divided by total outcomes, and the average excess return SHALL equal the arithmetic mean of all excess_return_vs_spy values. All three values SHALL be in [0.0, 1.0] for rates and finite for the average.

**Validates: Requirements 1.4**

### Property 5: Portfolio Period-Over-Period Delta Computation

*For any* two valid portfolio snapshots (current and previous) with non-negative portfolio_value, active_pool, reserve_pool, and finite cumulative_return, the period-over-period deltas SHALL equal (current - previous) for each field. When no previous snapshot exists, the deltas SHALL be zero.

**Validates: Requirements 1.3**

---

## Error Handling

### Data Collection Failures

| Scenario | Handling |
|----------|----------|
| No trading_decisions for period | Generate zero-activity report with note "No trading activity during this period" |
| No portfolio_snapshot for period | Use most recent snapshot before period_start; if none exists, use zero values |
| No prediction_outcomes for period | Skip recommendation accuracy validation; set validation_warnings noting missing data |
| No model_metric_snapshots for period | Model quality section shows NULL values for all metrics |
| Database connection failure during collection | Propagate error to job processor for retry |

### AI Summarization Failures

| Scenario | Handling |
|----------|----------|
| LLM timeout (>60s) | Retry up to max_retries (from agent config, default 2) |
| LLM returns empty response | Treat as failure, retry |
| LLM returns response > 200 words | Truncate to 200 words at sentence boundary |
| All LLM retries exhausted | Fall back to deterministic template summary |
| AgentConfigResolver returns None (agent not found) | Log error, use deterministic summary for all sections |
| Chunk merge LLM call fails | Use concatenation of chunk summaries (joined with newlines) |

### Validation Edge Cases

| Scenario | Handling |
|----------|----------|
| Snapshot value is 0 and computed value is non-zero | Flag as warning with pct_difference = 100.0 |
| Both snapshot and computed values are 0 | No warning (0% difference) |
| Snapshot value is NULL | Skip validation for that metric, no warning |
| Computed value is NaN or infinity | Replace with 0.0, log warning |
| No prediction_outcomes to cross-reference | Skip recommendation accuracy validation entirely |

### Report Storage Failures

| Scenario | Handling |
|----------|----------|
| Unique constraint violation on insert | Use ON CONFLICT DO UPDATE to upsert |
| JSONB serialization failure | Log error with report structure, propagate to job processor |
| Report exceeds PostgreSQL JSONB size limit (~255 MB) | Extremely unlikely given report structure; log error if it occurs |

### Job Processing Failures

| Scenario | Handling |
|----------|----------|
| Job fails on first attempt | Retry with exponential backoff: 30s, 60s, 120s |
| Job fails after 3 retries | Mark job as failed, log error with full context |
| Duplicate job submitted for same period | Reject with log message, return without error |
| Redis connection failure | Job stays in queue, picked up on reconnection |

---

## Testing Strategy

### Property-Based Tests (Hypothesis)

Property-based tests use the Hypothesis library with `@settings(max_examples=100)`. Test files are prefixed `test_pbt_*` per project convention.

| Property | Test File | What It Tests |
|----------|-----------|---------------|
| Property 1: Chunking Round-Trip | `tests/test_pbt_report_chunking.py` | `chunk_data()` preserves content and respects size limits |
| Property 2: Report Serialization Round-Trip | `tests/test_pbt_report_serialization.py` | `ReportData.model_dump_json()` → `ReportData.model_validate_json()` round-trip |
| Property 3: Validation Discrepancy Detection | `tests/test_pbt_report_validation.py` | Discrepancy detection correctly flags >5% differences |
| Property 4: Recommendation Accuracy Aggregation | `tests/test_pbt_report_sections.py` | `build_recommendation_accuracy_section()` computes correct aggregates |
| Property 5: Portfolio Delta Computation | `tests/test_pbt_report_sections.py` | `build_pnl_section()` computes correct period-over-period deltas |

Each property test is tagged with a comment referencing the design property:
```python
# Feature: trading-feedback-engine, Property 1: Chunking round-trip and size constraint
```

### Unit Tests (pytest)

| Test File | Coverage |
|-----------|----------|
| `tests/test_report_sections.py` | Section builders with known inputs, edge cases (empty data, single position, zero-activity) |
| `tests/test_report_validator.py` | Specific discrepancy scenarios, boundary cases (exactly 5%), NULL snapshot values |
| `tests/test_report_summarizer.py` | Deterministic fallback summary, chunk splitting edge cases (empty input, single char) |
| `tests/test_report_models.py` | Pydantic model validation, enum constraints, default values |
| `tests/test_report_generator.py` | Orchestration with mocked dependencies, zero-activity report, upsert behavior |

### Integration Tests

| Test File | Coverage |
|-----------|----------|
| `tests/test_report_api.py` | API endpoints with seeded database, pagination, filtering by report_type and date range |
| `tests/test_report_storage.py` | Store/retrieve round-trip against real asyncpg pool, upsert behavior, unique constraint |

### Frontend Tests (Vitest)

| Test File | Coverage |
|-----------|----------|
| `frontend/src/test/reports.test.ts` | useReports and useReport hooks with MSW mocks, loading/error states |

### Test Configuration

- Python PBT: Hypothesis with `@settings(max_examples=100)`, files prefixed `test_pbt_*`
- Python unit/integration: pytest with pytest-asyncio for async code
- Frontend: Vitest with MSW for deterministic API mocking
- Lint: `ruff check services/` before all commits
- CI: Woodpecker runs all tests automatically on push to Gitea