miranov25
diff --git a/‎UTILS/dfextensions/dfdraw/channels.py‎
Lines changed: 205 additions & 66 deletions b/‎UTILS/dfextensions/dfdraw/channels.py‎
Lines changed: 205 additions & 66 deletions
diff --git a/‎UTILS/dfextensions/dfdraw/docs/STYLING_FRAMEWORK_DECISIONS.md‎
Lines changed: 32 additions & 0 deletions b/‎UTILS/dfextensions/dfdraw/docs/STYLING_FRAMEWORK_DECISIONS.md‎
Lines changed: 32 additions & 0 deletions
@@ -1,8 +1,8 @@
 """dfdraw.channels — N-Channel Framework (Phase 13.26.DF Phase B)
 
-This module implements Algorithm A from brainstorm v1.4 §3.1: automatic
-visual-channel assignment for N data channels (vector, group_by, quantiles,
-selection_delta, ...).
+Implements Algorithm A from brainstorm v1.4 §3.1: automatic visual-channel
+assignment for N data channels (vector, group_by, quantiles, selection_delta,
+...).
 
 Per Phase 13.26.DF v1.2 §5.2, the API is N-channel from day one:
 
@@ -19,21 +19,15 @@
 - Brainstorm v1.4 §3.1 (Algorithm A), §3.2 (default-style table), §10 (style
   sets), §13 (default-style table deliverable), §14 (phasing plan)
 - AD-44 through AD-59 — see ``docs/STYLING_FRAMEWORK_DECISIONS.md``
-
-Status
-------
-Phase 13.26.DF Commit 1 (scaffolding): module + dataclass + EXPLICIT_RULES
-table populated with the 7 Phase B entries. Function bodies raise
-``NotImplementedError("Phase 13.26.DF Commit 2: implementation pending")`` so
-that callers wired up in Commit 2 fail loudly until the algorithm lands.
-
-Existing 578 tests do not call this module (Commit 1 is pure scaffolding).
 """
 
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass
-from typing import Optional
+from typing import Optional, Sequence
+
+from .style import get_style_value
 
 
 # ----------------------------------------------------------------------------
@@ -80,25 +74,6 @@ class DataChannel:
     cost : int, default 1
         Visual-channel slots consumed. ``0`` for zero-cost modes; ``1`` for
         one-channel modes (the typical case).
-
-    Examples
-    --------
-    Phase B 3-channel call::
-
-        channels = [
-            DataChannel('vector',    is_categorical=True,  cardinality=3),
-            DataChannel('group_by',  is_categorical=True,  cardinality=5),
-            DataChannel('quantiles', is_categorical=False, cardinality=3,
-                        cost=1),
-        ]
-        # -> assign_channels(channels) returns:
-        #   {'group_by': 'color', 'vector': 'marker', 'quantiles': 'linestyle'}
-
-    Phase D extensibility (no API change)::
-
-        channels.append(DataChannel('selection_delta',
-                                    is_categorical=False,
-                                    cardinality=4, cost=0))
     """
 
     name: str
@@ -120,7 +95,7 @@ class DataChannel:
 # Source: Phase 13.26.DF v1.2 §3.2 default-style table.
 # Provenance: AD-56 (3-channel default), brainstorm v1.4 §13 deliverable table.
 
-EXPLICIT_RULES: dict[frozenset[str], dict[str, str]] = {
+EXPLICIT_RULES: "dict[frozenset, dict[str, str]]" = {
     # 1-channel cases
     frozenset({'vector'}):    {'vector':    'color'},
     frozenset({'group_by'}):  {'group_by':  'color'},
@@ -140,10 +115,10 @@ class DataChannel:
 
 
 # ----------------------------------------------------------------------------
-# Public API (stubs — Commit 2 implements)
+# Public API
 # ----------------------------------------------------------------------------
 
-def assign_channels(channels: list[DataChannel]) -> dict[str, str]:
+def assign_channels(channels: Sequence[DataChannel]) -> "dict[str, str]":
     """Algorithm A: assign visual channels to active data channels.
 
     Resolution order per channel (per v1.2 §5.2):
@@ -154,9 +129,14 @@ def assign_channels(channels: list[DataChannel]) -> dict[str, str]:
     4. Greedy priority-list fallback (``channels.priority.categorical`` /
        ``channels.priority.ordinal``)
 
+    Then:
+
+    5. Collision check (Step 4): no two channels assigned to the same visual
+    6. Capacity check (Step 5): cardinality must not exceed cycle capacity
+
     Parameters
     ----------
-    channels : list[DataChannel]
+    channels : Sequence[DataChannel]
         All data channels for this draw call. Zero-cost channels (cost=0)
         are tracked in the input list but absent from the output dict.
 
@@ -168,59 +148,218 @@ def assign_channels(channels: list[DataChannel]) -> dict[str, str]:
     Raises
     ------
     ValueError
-        On channel collision (Step 4) or capacity overflow (Step 5).
-        Behaviour controlled by ``channels.overflow`` style key.
-
-    Notes
-    -----
-    Idempotency contract per v1.2 §5.5: this function is called at most once
-    per top-level user call. The vector path (``_draw_vector()``) calls it
-    once and forwards the resolved styles via kwargs to ``draw_profile()``;
-    ``draw_profile()`` only calls ``assign_channels()`` itself when not
-    invoked from a vector parent (detected via ``quantile_style is None``
-    at entry).
+        On channel collision (Step 4) or capacity overflow (Step 5) when
+        ``channels.overflow`` style key is ``"error"`` (default).
     """
-    raise NotImplementedError(
-        "Phase 13.26.DF Commit 2: implementation pending. "
-        "Scaffolding only — see PHASE_13_26_DF_v1_2_Proposal_NChannelFramework.md §5.2."
-    )
-
-
-def build_factored_legend(ax, assignment: dict[str, str], channel_entries: dict):
+    # Step 0: filter to active channels with cost > 0 (zero-cost modes
+    # consume no visual channel slot per brainstorm v1.4 §3.1 Step 0).
+    active = [c for c in channels if c.cost > 0]
+
+    if not active:
+        return {}
+
+    result: "dict[str, str]" = {}
+    used_visual: "set[str]" = set()
+
+    # Priority 1: per-call kwarg (highest precedence — always wins).
+    # Priority 2: style pinned default `channels.default.<name>`.
+    for c in active:
+        if c.requested_style is not None:
+            result[c.name] = c.requested_style
+            used_visual.add(c.requested_style)
+        else:
+            pinned = get_style_value(f"channels.default.{c.name}")
+            if pinned is not None:
+                result[c.name] = pinned
+                used_visual.add(pinned)
+
+    # Priority 3: explicit-case rule for known patterns (G-7: keyed on
+    # frozenset of all active-channel names; entries that conflict with
+    # already-resolved channels are skipped, leaving them for Priority 4).
+    unresolved_names = [c.name for c in active if c.name not in result]
+    if unresolved_names:
+        active_set = frozenset(c.name for c in active)
+        rule = EXPLICIT_RULES.get(active_set)
+        if rule is not None:
+            still_unresolved = []
+            for name in unresolved_names:
+                visual = rule.get(name)
+                if visual is not None and visual not in used_visual:
+                    result[name] = visual
+                    used_visual.add(visual)
+                else:
+                    still_unresolved.append(name)
+            unresolved_names = still_unresolved
+
+    # Priority 4: greedy priority-list fallback (Step 3 in §3.1).
+    # Used when (a) the active-set isn't in EXPLICIT_RULES (e.g., a future
+    # combination not yet covered) or (b) per-call kwargs displaced the
+    # explicit rule's intended assignment.
+    if unresolved_names:
+        cat_priority = get_style_value(
+            "channels.priority.categorical",
+            ["color", "linestyle", "marker"],
+        )
+        ord_priority = get_style_value(
+            "channels.priority.ordinal",
+            ["linestyle", "marker", "color"],
+        )
+        active_by_name = {c.name: c for c in active}
+        # Sort: categorical first, then by descending cardinality
+        # (per brainstorm v1.4 §3.1 Step 1).
+        unresolved_sorted = sorted(
+            unresolved_names,
+            key=lambda n: (
+                0 if active_by_name[n].is_categorical else 1,
+                -active_by_name[n].cardinality,
+            ),
+        )
+        overflow_mode = get_style_value("channels.overflow", "error")
+        for name in unresolved_sorted:
+            c = active_by_name[name]
+            priority = cat_priority if c.is_categorical else ord_priority
+            assigned = None
+            for visual in priority:
+                if visual not in used_visual:
+                    assigned = visual
+                    break
+            if assigned is None:
+                msg = (
+                    f"Cannot assign visual channel for '{name}' "
+                    f"({c.cardinality} values). "
+                    f"All channels in use: {sorted(used_visual)}. "
+                    f"Reduce active dimensions or use facet=True."
+                )
+                if overflow_mode == "error":
+                    raise ValueError(msg)
+                warnings.warn(msg, UserWarning, stacklevel=2)
+                assigned = priority[0]  # graceful fallback under "warn"
+            result[name] = assigned
+            used_visual.add(assigned)
+
+    # Step 4: collision check. Two channels assigned to the same visual is
+    # an error — typically caused by per-call kwargs or pinned defaults that
+    # conflict with the explicit rule.
+    inverse: "dict[str, str]" = {}
+    for name, visual in result.items():
+        if visual in inverse:
+            other = inverse[visual]
+            raise ValueError(
+                f"Channel collision: '{name}' and '{other}' both assigned "
+                f"to '{visual}'. "
+                f"Override with {name}_style= or {other}_style=, "
+                f"or change channels.default.* in style."
+            )
+        inverse[visual] = name
+
+    # Step 5: capacity check. A data channel's cardinality must fit within
+    # its assigned visual channel's cycle length.
+    cycle_lengths = {
+        'color': get_style_value("channels.cycles.color_count", 10),
+        'linestyle': len(get_style_value(
+            "channels.cycles.linestyle", ["-", "--", "-.", ":"])),
+        'marker': len(get_style_value(
+            "channels.cycles.marker",
+            ["o", "s", "^", "D", "v", "<", ">", "p"])),
+    }
+    overflow_mode = get_style_value("channels.overflow", "error")
+    for c in active:
+        visual = result.get(c.name)
+        if visual is None:
+            continue
+        capacity = cycle_lengths.get(visual, 10)
+        if c.cardinality > capacity:
+            msg = (
+                f"{c.name} ({c.cardinality} values) exceeds "
+                f"{visual} cycle capacity ({capacity}).\n"
+                f"  Options: top_k={capacity}, "
+                f"facet=True, group_by_bins={capacity}"
+            )
+            if overflow_mode == "error":
+                raise ValueError(msg)
+            warnings.warn(msg, UserWarning, stacklevel=2)
+
+    return result
+
+
+def build_factored_legend(ax, assignment, channel_entries, **legend_kwargs):
     """Build a factored legend with one section per data channel.
 
     Per v1.2 §6: when ``channels.legend.factored`` is True (default) and
     >= 2 channels are active, render section headers per channel with
     proxy artists for each entry. Total entries = sum(cardinalities) not
     product (e.g., 5 + 3 + 3 = 11 instead of 5 * 3 * 3 = 75).
 
-    When ``channels.legend.factored`` is False, fall through to the existing
-    flat deduplicated legend (``_add_vector_main_legend_dedup`` from FIX1).
-
     Parameters
     ----------
     ax : matplotlib.axes.Axes
-        Target axes to attach the legend to.
+        Target axes.
     assignment : dict[str, str]
         Output of ``assign_channels()`` — maps channel name to visual channel.
-    channel_entries : dict
-        Per-channel entries to render in the legend, e.g.::
+    channel_entries : dict[str, list[tuple[str, Any]]]
+        Per-channel entries to render::
 
             {
                 'vector':    [('dy_I0', 'o'), ('dy_I1', 's'), ...],
                 'group_by':  [('mP4 in [0,2)', 'C0'), ...],
                 'quantiles': [('q=10%', '--'), ...],
             }
 
+        Each tuple is (label, visual-style-value).
+    **legend_kwargs
+        Forwarded to ``ax.legend()`` (e.g., ``loc``, ``fontsize``).
+
     Returns
     -------
-    matplotlib.legend.Legend
-        The factored legend artist attached to ``ax``.
+    matplotlib.legend.Legend or None
+        Returns None if no entries to render.
     """
-    raise NotImplementedError(
-        "Phase 13.26.DF Commit 2: implementation pending. "
-        "Scaffolding only — see PHASE_13_26_DF_v1_2_Proposal_NChannelFramework.md §6."
-    )
+    import matplotlib.pyplot as plt
+
+    handles = []
+    labels = []
+
+    # Stable section order: keep the order in which channels appear in
+    # the assignment dict (Python 3.7+ guarantees insertion order).
+    for ch_name, visual in assignment.items():
+        entries = channel_entries.get(ch_name, [])
+        if not entries:
+            continue
+        # Section header — invisible artist with a section text label.
+        handles.append(plt.Line2D([], [], color='none', label=''))
+        labels.append(f"— {ch_name} ({visual}) —")
+        # Per-entry proxy artist matched to the visual channel.
+        for entry_label, style_value in entries:
+            if visual == 'color':
+                h = plt.Line2D(
+                    [], [], color=style_value, marker='s',
+                    linestyle='none', markersize=8,
+                )
+            elif visual == 'linestyle':
+                h = plt.Line2D(
+                    [], [], color='gray', linestyle=style_value,
+                    linewidth=1.5,
+                )
+            elif visual == 'marker':
+                h = plt.Line2D(
+                    [], [], color='gray', marker=style_value,
+                    linestyle='none', markersize=8,
+                )
+            else:
+                # Unknown visual — neutral fallback.
+                h = plt.Line2D([], [], color='gray')
+            handles.append(h)
+            labels.append(entry_label)
+
+    if not handles:
+        return None
+
+    legend_defaults = {
+        'loc': get_style_value("legend.loc", "best"),
+        'frameon': get_style_value("legend.frameon", True),
+    }
+    legend_defaults.update(legend_kwargs)
+    return ax.legend(handles, labels, **legend_defaults)
 
 
 __all__ = [
 
@@ -196,6 +196,37 @@ Extracted from Phase 13.25.DF + Phase 13.26.DF review cycles. These should bind
 - All 578 existing tests pass
 - Bundle: `reviewer.zip` for Commit 1 review (tag verification, scaffolding correctness)
 
+### Phase 13.26.DF Commit 2 implementation
+
+- Parent commit: `0df4c00b` (Phase 13.26.DF Commit 1 scaffolding)
+- Files modified: `dfdraw/channels.py` (stub → ~310 LOC implementation), `dfdraw/drawer.py` (Algorithm A wiring + cycle constants → style-key lookups + `quantile_style` forwarding), `dfdraw/plots/profile.py` (nested-band detection + channel-aware discrete rendering + `_render_quantile_nested_band`), `dfdraw/tests/test_channel_assignment.py` (50 skip stubs → 50 real test bodies)
+- Test count: 627 passed + 1 skipped + 0 failed (verified on architect MacOS env, 2026-05-06; +50 new tests vs Commit 1 baseline of 577)
+- No regressions in any pre-existing test
+- Pre-commit tag candidate: `PHASE_13_26_DF_v1_0_END`
+
+#### AD-60: FIX2 visual elements — channel-aware preservation
+
+**Decision:** Per v1.2 §11.3 directive ("Coder may preserve, redesign, or drop FIX2 elements"), Commit 2 **preserves** the FIX2 visual elements (on-line percentage annotations + linestyle cycle for discrete quantiles) as the **channel-aware default for `quantile_style='linestyle'`**, with two structural changes to align with the channel framework:
+
+1. **Cycle source:** the FIX2 hardcoded local `_ls_cycle = ['--', '-.', ':', (0, (3, 1, 1, 1))]` at `profile.py:559` is replaced with `get_style_value("channels.cycles.linestyle", default)[1:]`. The `[1:]` slice preserves the FIX2 invariant that **solid linestyle remains reserved for the central line** (now controlled by the first entry of `channels.cycles.linestyle`). Default cycle is `['-', '--', '-.', ':']`, so the discrete-quantile cycle is `['--', '-.', ':']` — one entry shorter than FIX2's hardcoded 4-entry cycle (the dash-dot-dot pattern `(0, (3, 1, 1, 1))` is dropped). For 4+ symmetric quantiles users are now routed to `nested_band` mode (AD-57) anyway, so the missing 4th linestyle is rarely needed; users requiring it can `set_style({'channels.cycles.linestyle': ['-', '--', '-.', ':', (0, (3, 1, 1, 1))]})`.
+
+2. **Annotation scope:** FIX2's on-line percentage annotations (`profile.py:564-577`) are preserved when `quantile_style='linestyle'` (the default), and **suppressed** when `quantile_style='marker'` or `quantile_style='color'`. Rationale: marker- and color-distinguished quantile lines need no on-line text to disambiguate; the legend handles it. Linestyle-distinguished lines benefit from on-line annotations because subtle linestyle differences are harder to read against a legend at a distance.
+
+**Provenance:** v1.2 §11.3 explicit recommendation; FIX2 commit `da8895e2` (PHASE_13_25_DF_FIX2_END).
+
+#### Behavior change recorded for transparency (per v1.2 §8.3 greenfield)
+
+Symmetric quantile lists with **>= 4 non-0.5 entries** now auto-detect as `nested_band` mode (AD-57, Option A) instead of `discrete`. This is a deliberate change to the auto-detection rule and is per architect amendment chat 2026-05-05: *"We did not use quentiles yet. We do not need to be back compatible. for quentiles"*.
+
+Affected examples:
+- `[0.05, 0.25, 0.5, 0.75, 0.95]` (5 entries with central): was `discrete`, now `nested_band` (2 alpha-stacked filled regions + central line)
+- `[0.05, 0.25, 0.75, 0.95]` (4 entries no central): was `discrete`, now `nested_band` (2 alpha-stacked filled regions)
+- `[0.01, 0.05, 0.25, 0.5, 0.75, 0.95, 0.99]` (3 pairs + central): was `discrete`, now `nested_band` (3 filled regions + central line)
+
+**To restore old behavior** on a per-call basis, pass `quantile_mode='discrete'` explicitly. The `stats_dict['quantiles_per_bin']` signature is preserved for both modes, so existing tests that only check the stats dict signature still pass.
+
+**Existing test affected:** `tests/test_quantiles_profile.py::TestQuantileMode::test_multi_pair_returns_discrete` — used to test that `[0.05, 0.25, 0.5, 0.75, 0.95]` returns discrete mode. Renamed to `test_multi_pair_returns_nested_band` and docstring updated in Commit 2 to reflect new contract (assertion still passes either way because `quantiles_per_bin` is set for both modes; only the mode name and intent change).
+
 ---
 
 *This document is authoritative for dfdraw architectural decisions. Modifications to AD entries require architect approval; appending new ADs follows the standard phase-decision workflow per `Organization-structure.md`. Governance principles (GP-N) are extracted from review-cycle lessons and bind future phases unless explicitly overridden by architect.*
@@ -205,3 +236,4 @@ Extracted from Phase 13.25.DF + Phase 13.26.DF review cycles. These should bind
 | Version | Date | Author | Change |
 |---|---|---|---|
 | 1.0 | 2026-05-05 | Claude49Coder | Initial seed in Phase 13.26.DF Commit 1. AD-44 through AD-59 + 5 governance principles + drafter rotation history + Phase 13.26.DF v1.2 audit trail. |
+| 1.1 | 2026-05-06 | Claude49Coder | Phase 13.26.DF Commit 2 audit-trail entry. AD-60 added (FIX2 visual-elements channel-aware preservation per v1.2 §11.3). Behavior-change record for `nested_band` auto-detection on symmetric 4+ entries. |