refactor(piecewise): per-tuple sign + categorized internal flow

[FBumann]

Refactor of the unreleased add_piecewise_formulation API on feat/piecewise-api-refactor. Targets the in-progress branch, not master; no external users yet.

What changes

• Per-tuple sign. Move the formulation-level sign= keyword onto the tuple it applies to: (y, y_pts, \"<=\") replaces sign=\"<=\". Each tuple carries an optional 3rd element (default \"==\"). The bounded tuple no longer has a special position — user tuple order is preserved end-to-end.
• Validation. At most one tuple may carry a non-equality sign; 3+ tuples must all be \"==\". The N-input bounded case is rejected with an error message that invites a GitHub issue rather than promising a specific future API shape.
• Categorized internal flow. New _PwlInputs dataclass carries categorized inputs (bounded_* vs pinned_*) through the dispatch chain (_build_links, _try_lp, _lp_eligibility, _add_continuous, _add_disjunctive). The "first tuple is special" positional convention is gone — every consumer reads the role explicitly.
• Docs/notebooks. Rewrite the user-facing docs and example notebooks to leverage the new notation. Drop the "first-tuple convention" / "N−1 jointly pinned" scaffolding that existed only to teach the old positional rule. Restrictions reframed as invitations.

Before / after

# before
m.add_piecewise_formulation((y, y_pts), (x, x_pts), sign=\"<=\")

# after
m.add_piecewise_formulation((y, y_pts, \"<=\"), (x, x_pts))

The old sign= keyword now raises a TypeError with a one-line pointer to the new shape — convenient while updating the in-repo callers, not a migration aid for external users.

Future work this enables

The tuple shape is now the right primitive across three distinct piecewise regimes — same (expr, breaks, [sign]) call, no public-API redesign needed for any of them:

Regime	Tuple form	What's needed beyond this PR
2-var equality / inequality	(y, y_pts), (x, x_pts) ± sign	Nothing — current behaviour
3+ var equality (e.g. CHP)	(power, p_pts), (fuel, f_pts), (heat, h_pts)	Nothing — current behaviour
2-D triangulated z ≥ f(x, y)	(z, z_pts, \">=\"), (x, x_pts), (y, y_pts), triangulation=tris	Sibling triangulation= kwarg + new builders

For the 2-D case specifically: vertex coordinates stay as plain 1-D (_vertex,) DataArrays on each tuple — they survive slicing, broadcast, and use the existing coercion/masking machinery. The simplex adjacency rides along as one shared sibling kwarg, not embedded in the breakpoint slices (which would force fragile attrs or a non-DataArray wrapper class). Internally, _PwlInputs would grow a single optional field triangulation: DataArray | None; the dispatcher branches on it; the formulation builders for the triangulated path are new but consume the same input carrier.

The N≥3-inequality slot we reserved at the parser is what makes this fit naturally — (z, z_pts, \">=\"), (x, x_pts), (y, y_pts) reads as z ≥ f(x, y) without contortion, and the N≥3 + non-equality validation can loosen to allow it specifically when triangulation is set.

Other follow-ups this also unlocks

• Friendly 2-arg alias (add_piecewise(y, x, x_pts, y_pts, sign=\"<=\")) — routes cleanly because role-categorization is explicit.
• Multi-bounded relations (if a use case appears) — the "at most one bounded tuple" check is a single line; the dispatch chain already handles per-tuple roles.
• API stabilization (drop EvolvingAPIWarning) — the shape we'd commit to is now structurally honest, with no positional convention to teach or maintain in docs.

Test plan

• pytest test/test_piecewise_constraints.py test/test_piecewise_feasibility.py — 518 passed
• pytest test/ --ignore=test/remote --ignore=test/test_optimization.py --ignore=test/test_solvers.py — 1578 passed
• ruff check + ruff format --check — clean
• mypy linopy/piecewise.py — clean
• Both example notebooks execute end-to-end against Gurobi

🤖 Generated with Claude Code