# Overflow recovery

`BudgetExceeded` is a structured recovery object, not only an error message. It contains the budget, required token total, overflow amount, token-profile identity and fingerprint, per-item cumulative costs, the item that crossed the budget, already excluded items, available strategies, and a partial manifest.

## Inspect and recover

The following example uses the deterministic approximate profile. Truncation is allowed only because the required Text item explicitly sets `truncatable=True`.

```{testcode}
import cognoxium as cx

frame = cx.CognitionFrame.from_records([
    {
        "id": "policy",
        "payload": "x" * 60,
        "sources": ["app://policy"],
        "trust": "trusted",
        "retention": "required",
        "truncatable": True,
        "created_at": "2026-01-01T00:00:00Z",
    }
])

try:
    frame.pack(budget=10, token_profile=cx.profiles.approximate())
except cx.BudgetExceeded as error:
    print(error.code)
    print(error.budget, error.required_tokens, error.overflow_tokens)
    print(error.exceeded_at_item_id)
    print(error.item_costs[0].to_dict())
    print(error.available_strategies)

pack = frame.pack(
    budget=10,
    token_profile=cx.profiles.approximate(),
    overflow=cx.Overflow.truncate_truncatable(side="tail"),
)
print(pack.manifest.total_tokens)
print(pack.manifest.truncations[0]["id"])
print(pack.manifest.truncations[0]["removed_tokens"])
```

```{testoutput}
CX_BUDGET_001
10 15 5
policy
{'id': 'policy', 'tokens': 15, 'cumulative_tokens': 15, 'retention': 'required', 'priority': 0.0, 'truncatable': True, 'min_tokens': 0}
('error', 'truncate_truncatable')
10
policy
5
```

## Recovery choices

1. **Increase the budget** when the destination supports it.
2. **Demote content before packing** only after the application decides it is no longer required.
3. **Opt into truncation** for Text that is safe to shorten.
4. **Reject or defer the model call** and surface the structured diagnostic to an operator.

Do not catch the exception and silently remove a required item.

## Truncation constraints

- Only Text with `truncatable=True` is eligible.
- `side="tail"` keeps a prefix; `side="head"` keeps a suffix.
- The marker is included in the token budget.
- `min_tokens` sets the minimum retained content-token count.
- JSON, Reference, Binary, and `truncatable=False` items are never partially truncated.
- If eligible truncation is insufficient, `BudgetExceeded` is raised again.
- Truncation creates a new content hash, records the original hash, adds lineage, and writes the token change to the manifest.

## Localization

The captured locale makes `str(error)` stable. Re-render without changing structured data:

```python
print(error.code)
print(error.render("en"))
print(error.render("ja"))
```

Program logic must use `error.code`, attributes, and `partial_manifest`, never the translated messages.