Split Map2d.iter_data overloads by direction literal

[nikobockerman]

The iter_data overloads came in pairs per arity: one keyed on Literal[IterDirection.Rows] returning row-major tuples, and a general one accepting any IterDirection and returning column-major tuples, the general signature declared first.

Overload resolution picks the first match, and Literal[IterDirection.Rows] is assignable to IterDirection, so the general signature swallowed every call that named IterDirection.Rows explicitly and typed its result as column-major - the transpose of what the implementation yields. Merely declaring the literal signature first moves that unsoundness rather than removing it: the general signature then still promises column-major for an argument that may be Rows at run time, which mypy reports as an overload-overlap error.

Give each arity three signatures instead: Literal[IterDirection.Rows], Literal[IterDirection.Columns], and a general IterDirection returning the union of both shapes. The two literal signatures are disjoint, and each returns a subtype of the union the general signature promises, so no unsafe overlap is left. The union is also the honest answer for a caller whose direction is only known as an IterDirection, since iter_data branches on that value at run time.

Behaviour is unchanged and no call site needed adjusting.

[Copilot]

🟢 Approval recommended

The overload restructuring matches the runtime branching behavior, removes the documented typing unsoundness, and doesn’t alter runtime logic.

Pull request overview

This PR fixes type-checking unsoundness in Map2d.iter_data overloads by making the overload set disjoint for Rows vs Columns literals and making the non-literal overload return the honest union shape that matches the runtime branch on direction.

Changes:

• Split iter_data overloads (for each arity) into Literal[IterDirection.Rows], Literal[IterDirection.Columns], and a general IterDirection overload returning a union of both iterator shapes.
• Ensured calls explicitly passing IterDirection.Rows are typed as row-major (matching implementation), rather than being swallowed by a broader overload.

File summaries

File	Description
solvers/python/src/aoc/tooling/map.py	Reworks iter_data overload signatures to avoid overload overlap and align static return types with runtime behavior.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.