Fix non-terminating and exponential traversal of exception graphs

[Heknon]

__cause__/__context__ form an arbitrary directed graph, not a tree, but both the save and load paths walked them recursively as if they were one. That produced three distinct failures, all fixed here.

1. Cycles never terminated

raise e from e makes an exception its own cause. Saving one died with RecursionError, as did every other cycle shape reachable in Python: mutual __cause__ links, a manually assigned __context__, and a group whose cause is itself.

2. Shared nodes were re-expanded exponentially

This is the one that hurts in practice. raise X from Y sets both X.__cause__ and X.__context__ to Y, so the ordinary chaining idiom produces a diamond. Walking it as a tree revisits the shared node down both edges, so a chain of n exceptions costs 2**n. This one terminates, which is why it surfaced as a load that ran for hours rather than as an error.

All figures below use minimal frames, so they measure structure rather than payload.

Before — 2**(n+1)-1 nodes, everything doubling per link:

chain links	nodes	dump size	save	load
4	31	29 KB	1 ms	1 ms
8	511	476 KB	13 ms	12 ms
12	8,191	7.6 MB	191 ms	306 ms
16	131,071	122 MB	6.1 s	7.6 s

After — n+1 nodes, flat at ~930 bytes per link:

chain links	nodes	dump size	save	load
4	5	4.7 KB	0.31 ms	0.15 ms
8	9	8.3 KB	0.38 ms	0.26 ms
16	17	15.5 KB	0.61 ms	0.55 ms
64	65	59 KB	1.98 ms	1.69 ms
256	257	233 KB	8.91 ms	6.62 ms
1024	1025	934 KB	69.8 ms	27.8 ms

At the last depth both versions can do, 16 links, load goes from 7.6 s to 0.55 ms. Scaling is linear: 256× the links gives 205× the nodes, 199× the bytes and 185× the load time. The old code could not have reached 1024 links at all — that would have been 2**1025 nodes.

Nothing about the dump format changed to achieve this. pickle could always represent a shared node; the old code simply never handed it one, having already expanded the graph into 131,071 distinct objects in memory before pickle saw it. A cycle now costs a two-byte BINGET back-reference.

At the depth this actually bites

The table stops at 16 links because that is the deepest both versions can do. The failures that prompted this were deeper. Working back from the measured curve, a load that ran for 12 hours is a chain of roughly 27–29 links — 28.5 with minimal frames, nearer 27 with app-sized ones, where the per-node cost is around six times higher.

That same dump, after the fix:

chain links	nodes	dump size	save	load
24	25	22 KB	0.74 ms	0.64 ms
27	28	25 KB	0.77 ms	0.70 ms
28	29	26 KB	0.84 ms	0.72 ms
30	31	28 KB	0.86 ms	1.32 ms

43,200 s → 0.72 ms, about a 60-million-fold difference. It is that large because the change is 2**n → n, not a constant factor: at 29 links the old dump held roughly 537 million exception nodes (2**29-1) where the new one holds 29. Almost all of the work stopped existing rather than getting faster.

Two honest caveats. The 12-hour figure is extrapolated, not measured — but from measured data: across the nine pre-fix points timed here (k=8→16) the load ratio per added link averaged 2.26 (range 1.88–2.86), and the extrapolation runs from the measured 7.578 s at k=16. And the depth is a range rather than a number because frame size moves it: heavier frames cost more per node, so fewer links reach 12 hours.

Cases that previously produced an error rather than a number

case	before	after
raise e from e	RecursionError	1 node, 2.1 KB, save 0.20 ms, load 0.10 ms
mutual a ↔ b cycle	RecursionError	2 nodes, 2.5 KB, save 0.18 ms, load 0.07 ms
400-link acyclic chain, recursion limit 200	RecursionError	401 nodes, 31 KB, save 3.09 ms, load 1.12 ms

The last row is worth noting separately: it contains no cycle at all. Deep-but-ordinary cause chains failed purely on recursion depth, and the iterative walk removes that ceiling too.

3. Loaded exceptions could not be formatted

Separately, traceback.format_exception raised RuntimeError: generator raised StopIteration for every loaded dump, cycles or not — so a restored exception could not be printed, logged, or rendered by anything built on traceback. That defeats the point of reconstructing real frames.

Reconstructed frames deliberately carry a synthetic (empty) code object, because accessing f_locals on a frame built by PyFrame_New over real optimized bytecode segfaults. The traceback objects were still built with the original tb_lasti, which indexes into the original bytecode. Pairing the two made traceback._get_code_position search a two-entry co_positions() for instruction lasti // 2 — measured as index 33 against 2 available entries. A negative tb_lasti is the stdlib's own signal for "no instruction position available"; it then falls back to tb_lineno, which is restored accurately.

Approach

Both paths now memoize on identity and walk iteratively:

• _serialize_exc_data builds each node once and links them with a worklist, so the dump mirrors the original graph — a cycle stays a cycle, a node reachable twice stays one shared node. pickle reproduces that sharing via its memo, so a cycle costs a 2-byte back-reference rather than a copy.
• _reconstruct_exc_data builds every exception first, then wires __cause__/__context__ from the identity map. Deferring the links is what restores a cycle as a genuine cycle instead of an endless chain of copies. Group members are ordered before their group, since a group can only be built once its members exist.

Being iterative also removes the recursion-depth ceiling on legitimately deep cause chains, which previously failed well before any cycle was involved.

walk_exception_data is added as public API: consumers of parse_traceback now need a traversal that stops at nodes it has already seen, since a naive recursive walk no longer terminates and both dataclasses.asdict() and json.dumps() fail outright on a cycle. Its id()s are the stable key for emitting references instead of nesting, which is what makes a cyclic graph representable in JSON at all.

Compatibility

Verified rather than assumed, by reconstructing the exact shape the previous save_traceback wrote (cause and context as separate duplicated nodes):

• Old dumps do not fail. The on-disk layout is unchanged — no field added, removed or renamed — so an old dump parses, loads and formats under this version. They also gain the formatting fix, having previously failed to format at all.
• Old dumps keep their bloat. The duplication lives in the file, so an old five-link dump still expands to 63 nodes where a freshly saved one holds 6. Re-saving is what shrinks it.
• A new dump of a genuine cycle cannot be read by an older release — the pre-fix reader follows __cause__ forever. An ordinary new dump still reads fine on an older version. This is why the version goes to 0.4.0 rather than a patch bump.

Documented in the README so the "loads fine but stays bloated" distinction is not discovered as a surprise.

Testing

15 new tests across tests/test_exception_cycles.py and tests/test_traceback_formatting.py; all of them fail on the current main. 58 pass in total. ruff format, ruff check and ty check are clean, and every commit in the branch is independently green (48 → 52 → 58 → 58), so the history stays bisectable.

One limitation worth stating: the ^^^^ column markers are unavailable on reconstructed frames. Column spans live in the real code object's co_positions(), and that is exactly the object that cannot be kept without segfaulting on f_locals. Line-level fidelity is recovered; column-level is not, short of storing position tables separately. This is noted in the README rather than left as a surprise.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CJBKuuFRsXohzgomc7sLiy