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.

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"])

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:

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.