# Decision Correction Reference

## Overview

The correction subsystem allows operators to modify a plan's decision tree
after execution by either **reverting** a subtree of decisions or
**appending** new decisions as a child plan.

## Correction Modes

### Revert

Invalidates the targeted decision and every descendant reachable via
BFS traversal.  Associated artifacts are archived and affected child
plans are rolled back.

```text
          ┌─── D1 (target) ◄── revert starts here
          │       │
          │    ┌──┴──┐
          │    D2    D3          ← all invalidated
          │          │
          │          D4          ← also invalidated
```

### Append

Preserves the original decision and spawns a **new child plan** rooted
at the target node.  The child plan carries the operator's guidance and
produces additional decisions without disturbing the existing tree.

```text
          D1 (target)
           │
        ┌──┴──────────┐
        D2 (original)  CP-new   ← child plan appended
```

## Impact Analysis — BFS Algorithm

Impact analysis uses breadth-first search over the decision tree's
adjacency list (parent → children mapping):

```python
from collections import deque

def compute_affected_subtree(target_id, tree):
    affected = []
    queue = deque([target_id])
    while queue:
        node = queue.popleft()
        affected.append(node)
        queue.extend(tree.get(node, []))
    return affected
```

### Risk Classification

| Affected Count | Risk Level |
|----------------|------------|
| ≤ 3            | low        |
| 4 – 10         | medium     |
| > 10           | high       |

## Dry-Run Output

A dry-run report contains:

- **impact** — Full `CorrectionImpact` with affected decisions, files,
  child plans, estimated cost, and risk level.
- **decisions_to_invalidate** — Decision IDs that *would* be marked
  invalid (revert mode only).
- **child_plans_to_rollback** — Child plans that *would* be rolled back.
- **estimated_recompute_time_seconds** — Wall-clock estimate.
- **warnings** — Human-readable cautions (e.g. high risk).

## Status Lifecycle

```text
PENDING → ANALYZING → EXECUTING → APPLIED
                                 → FAILED
         PENDING → CANCELLED
         ANALYZING → CANCELLED
```

## Service API

| Method                      | Description                                   |
|-----------------------------|-----------------------------------------------|
| `request_correction()`      | Create a new correction request               |
| `analyze_impact()`          | BFS impact analysis on the decision tree      |
| `generate_dry_run_report()` | Full report without side effects               |
| `execute_revert()`          | Invalidate subtree + archive artifacts         |
| `execute_append()`          | Spawn child plan preserving original decision  |
| `execute_correction()`      | Dispatch to revert or append based on mode     |
| `get_correction()`          | Retrieve a correction by ID                    |
| `list_corrections()`        | List corrections (optional plan_id filter)     |
| `list_attempts()`           | List execution attempts for a correction       |
| `cancel_correction()`       | Cancel a pending/analyzing correction          |