Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/kicad

Analyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trust_summary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicad_sch, .kicad_pcb, .kicad_pro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question.

FileKindSize
SKILL.mdskill md79.1 KB
references/config-reference.mdmarkdown19.1 KB
references/datasheet-verification.mdmarkdown16.5 KB
references/deep-review.mdmarkdown9.7 KB
references/design-intent.mdmarkdown5.6 KB
references/diff-analysis.mdmarkdown17.6 KB
references/file-formats.mdmarkdown15.1 KB
references/gerber-parsing.mdmarkdown33.5 KB
references/manual-gerber-parsing.mdmarkdown24.5 KB
references/manual-pcb-parsing.mdmarkdown17.2 KB
references/manual-schematic-parsing.mdmarkdown12.8 KB
references/net-tracing.mdmarkdown12.0 KB
references/oshwa-certification.mdmarkdown4.5 KB
references/output-schema.mdmarkdown33.4 KB
references/pcb-layout-analysis.mdmarkdown27.3 KB
references/pdf-schematic-extraction.mdmarkdown15.2 KB
references/report-generation.mdmarkdown56.3 KB
references/schematic-analysis.mdmarkdown63.9 KB
references/standards-compliance.mdmarkdown33.5 KB
references/supplementary-data-sources.mdmarkdown12.5 KB
references/what-if.mdmarkdown19.5 KB
review/README.mdmarkdown4.1 KB
review/fixtures/deep_review.example.jsonconfig1.2 KB
review/fixtures/design_context.example.jsonconfig388 B
review/fixtures/review_annotations.example.jsonconfig707 B
review/prompts/design_context.mdmarkdown4.9 KB
review/schemas/deep_review.schema.jsonconfig3.3 KB
review/schemas/design_context.schema.jsonconfig2.2 KB
review/schemas/review_annotations.schema.jsonconfig1.9 KB
review/scripts/_mini_jsonschema.pyscript6.6 KB
review/scripts/build_review_plan.pyscript2.3 KB
review/scripts/deep_review_gate.pyscript27.3 KB
review/scripts/merge_annotations.pyscript7.0 KB
review/scripts/validate_review.pyscript2.6 KB
scripts/.gitignoreother13 B
scripts/README.mdmarkdown23.4 KB
scripts/analysis_cache.pyscript42.1 KB
scripts/analyze_gerbers.pyscript90.9 KB
scripts/analyze_pcb.pyscript7.4 KB
scripts/analyze_schematic.pyscript6.7 KB
scripts/analyze_thermal.pyscript48.5 KB
scripts/analyzer_envelope.pyscript15.5 KB
scripts/capability_mode.pyscript10.2 KB
scripts/check_report_sections.pyscript10.6 KB
scripts/cross_analysis.pyscript69.4 KB
scripts/cross_verify.pyscript23.1 KB
scripts/design_intent.pyscript13.5 KB
scripts/detection_schema.pyscript26.0 KB
scripts/detector_helpers.pyscript15.2 KB
scripts/diff_analysis.pyscript23.5 KB
scripts/diff_engine.pyscript47.2 KB
scripts/domain_detectors.pyscript260.5 KB
scripts/envelopes/__init__.pyscript0 B
scripts/envelopes/cross_analysis.pyscript5.9 KB
scripts/envelopes/gerber.pyscript16.1 KB
scripts/envelopes/pcb.pyscript25.9 KB
scripts/envelopes/schematic.pyscript23.1 KB
scripts/envelopes/thermal.pyscript7.4 KB
scripts/export_issues.pyscript27.6 KB
scripts/fab_release_gate.pyscript29.8 KB
scripts/finding_schema.pyscript25.7 KB
scripts/gen_output_schema_md.pyscript9.2 KB
scripts/inputs_builder.pyscript4.0 KB
scripts/kicad_core/__init__.pyscript0 B
scripts/kicad_core/classify.pyscript32.5 KB
scripts/kicad_core/cli.pyscript4.2 KB
scripts/kicad_core/coords.pyscript2.0 KB
scripts/kicad_core/diagnostics.pyscript1.9 KB
scripts/kicad_core/executables.pyscript1.0 KB
scripts/kicad_core/fields.pyscript5.9 KB
scripts/kicad_core/fileio.pyscript5.4 KB
scripts/kicad_core/hotloop.pyscript3.1 KB
scripts/kicad_core/instances.pyscript5.7 KB
scripts/kicad_core/model.pyscript4.8 KB
scripts/kicad_core/netnames.pyscript19.1 KB
scripts/kicad_core/netquery.pyscript6.7 KB
scripts/kicad_core/pairing.pyscript1.9 KB
scripts/kicad_core/parts.pyscript28.9 KB
scripts/kicad_core/passives.pyscript10.0 KB
scripts/kicad_core/pdn.pyscript1011 B
scripts/kicad_core/project.pyscript43.2 KB
scripts/kicad_core/render.pyscript2.7 KB
scripts/kicad_core/sexp.pyscript12.6 KB
scripts/kicad_core/textvars.pyscript5.4 KB
scripts/kicad_core/token_cache.pyscript2.2 KB
scripts/kicad_core/values.pyscript14.1 KB
scripts/kicad_types.pyscript15.1 KB
scripts/lifecycle_audit.pyscript6.7 KB
scripts/lifecycle_engine.pyscript52.8 KB
scripts/lookup_detectors.pyscript29.9 KB
scripts/lookup_helpers.pyscript3.0 KB
scripts/methodology_gerbers.mdmarkdown23.1 KB
scripts/methodology_pcb.mdmarkdown22.2 KB
scripts/methodology_schematic.mdmarkdown43.1 KB
scripts/netlist_queries.pyscript4.2 KB
scripts/output_filters.pyscript16.8 KB
scripts/output_io.pyscript5.3 KB
scripts/pcb/__init__.pyscript0 B
scripts/pcb/assembly.pyscript58.3 KB
scripts/pcb/connectivity.pyscript27.7 KB
scripts/pcb/copper.pyscript61.0 KB
scripts/pcb/dfm.pyscript56.9 KB
scripts/pcb/geometry.pyscript59.5 KB
scripts/pcb/pipeline.pyscript30.3 KB
scripts/pcb/presentation.pyscript24.3 KB
scripts/pcb/reader.pyscript87.1 KB
scripts/pcb/routing.pyscript53.5 KB
scripts/project_config.pyscript23.1 KB
scripts/risk_summary.pyscript3.1 KB
scripts/run_id.pyscript1.7 KB
scripts/schema_codec.pyscript5.0 KB
scripts/schematic/__init__.pyscript0 B
scripts/schematic/audits.pyscript56.0 KB
scripts/schematic/bom_stats.pyscript6.1 KB
scripts/schematic/connectivity.pyscript62.9 KB
scripts/schematic/erc_pins.pyscript8.4 KB
scripts/schematic/hierarchy.pyscript21.5 KB
scripts/schematic/ic_analysis.pyscript21.4 KB
scripts/schematic/legacy_reader.pyscript49.4 KB
scripts/schematic/net_analysis.pyscript75.5 KB
scripts/schematic/pipeline.pyscript72.2 KB
scripts/schematic/presentation.pyscript20.9 KB
scripts/schematic/reader.pyscript64.7 KB
scripts/schematic/system_analyses.pyscript126.9 KB
scripts/signal_detectors.pyscript248.0 KB
scripts/summarize_findings.pyexecutablescript17.4 KB
scripts/validation_detectors.pyscript75.3 KB
scripts/what_if.pyscript68.4 KB

scripts/signal_detectors.py

View on GitHub
"""
Signal path detector functions extracted from analyze_signal_paths().

Each detector takes an AnalysisContext (ctx) and returns its detection results.
Some detectors also take prior results for cross-references.
"""

import math
import re
from dataclasses import dataclass

from kicad_core.parts import (
    _LOAD_TYPE_KEYWORDS,
    LOAD_SWITCH_KEYWORDS,
    names_load_switch,
    lookup_regulator_vref as _lookup_regulator_vref,
    lookup_switching_freq,
    default_switching_freq,
    match_known_switching as _match_known_switching,
)
from kicad_core.classify import classify_jumper_default_state
from kicad_core.values import format_frequency as _format_frequency, parse_value
from kicad_core.netnames import (
    is_power_net_name,
    is_usb_data_net_name,
    negative_split_rails,
    net_leaf,
    parse_voltage_from_net_name as _parse_voltage_from_net_name,
)
from kicad_core.netquery import build_bridge_facts, build_ref_pins, conductor_of, tie_conductors
from kicad_types import AnalysisContext
from finding_schema import make_provenance, make_finding, Det
from detector_helpers import index_two_pin_components, get_components_by_type, get_unique_ics
from detector_helpers import group_members, group_part, group_reps, group_value, parallel_groups

from lookup_helpers import get_facts, has_data, best, facts_trusted


# ---------------------------------------------------------------------------
# Shared helpers
# ---------------------------------------------------------------------------

# Gate-drive bootstrap pins: their supply is a capacitor to the switch node,
# so having no DC path to a rail is the datasheet circuit, not a fault. Many
# vendor symbols type them power_in. Same names detect_power_regulators uses.
_BOOTSTRAP_PIN_TOKENS = frozenset({"BST", "BOOT", "BOOTSTRAP", "CBST"})


# Regulator output pin names (exact parts of a composite pin name).
_VOUT_PIN_NAMES = frozenset({"VOUT", "VO", "OUT", "OUTPUT"})


def _classify_load(ctx: AnalysisContext, net_name, exclude_ref):
    """Classify what's on a net as a load type.

    Checks net name keywords first (motor, heater, fan, solenoid, valve,
    pump, relay, speaker, buzzer, lamp) for cases where the net name
    reveals the load type better than the connected components.
    Falls back to component-type classification.
    """
    # Net name keyword classification — catches loads driven through
    # connectors or across sheet boundaries where component type alone
    # would just show "connector" or "other"
    if net_name:
        nu = net_name.upper()
        for load_type, keywords in _LOAD_TYPE_KEYWORDS.items():
            if any(kw in nu for kw in keywords):
                return load_type

    comps = ctx.nq.components_on_net(net_name, exclude_refs={exclude_ref})
    types = {c["type"] for c in comps}
    if "inductor" in types:
        return "inductive"
    if "led" in types:
        return "led"
    if types == {"resistor"} or types == {"resistor", "capacitor"}:
        return "resistive"
    if "connector" in types:
        return "connector"
    if "ic" in types:
        return "ic"
    if "transistor" in types:
        return "transistor"  # cascaded
    return "other"


def _parse_crystal_frequency(value_str: str) -> float | None:
    """Parse crystal frequency from value string or part number.

    Tries parse_value() first, then regex for embedded MHz/kHz patterns
    like "YIC-12M20P2" → 12e6, "ABM8-25.000MHZ" → 25e6.
    """
    result = parse_value(value_str)
    if result is not None:
        return result
    if not value_str:
        return None
    # Explicit MHz/kHz in value. A comma between digits is a decimal mark ("9,84375 MHz")
    # only in a number that stands alone with at most three integer digits; in
    # "HC49,16MHz" and "3225,16MHz" the digits before the comma are a package code.
    for unit, scale in (('[Mm][Hh][Zz]', 1e6), ('[Kk][Hh][Zz]', 1e3)):
        m = re.search(r'(?<![A-Za-z0-9.,])(\d{1,3},\d+)\.?\s*' + unit, value_str)
        if not m:
            m = re.search(r'(\d+\.?\d*)\s*' + unit, value_str)
        if m:
            return float(m.group(1).replace(",", ".")) * scale
    # MPN patterns: "YIC-12M20P2" → 12MHz, "-25M000" → 25MHz
    m = re.search(r'[-_](\d+)[Mm]\d', value_str)
    if m:
        return float(m.group(1)) * 1e6
    return None


# Typical crystal load capacitance by frequency — used as fallback when the
# crystal value string doesn't include a pF specification.
# Sources: ECS crystal catalog (2024), Abracon AB series, Murata SA series.
_CRYSTAL_DEFAULT_CL = {
    32768: 12.5,         # Watch crystals: almost universally 12.5 pF
    100e3: 12.5,
    1e6: 12.5,
    2e6: 12.5,
    3.579545e6: 20.0,    # NTSC colorburst — historically 20 pF
    4e6: 12.5,
    8e6: 18.0,
    10e6: 20.0,
    12e6: 20.0,
    16e6: 20.0,
    20e6: 18.0,
    24e6: 10.0,           # 24 MHz: 10 pF (STM32 standard)
    25e6: 10.0,           # 25 MHz: 10 pF (Ethernet PHY standard)
    26e6: 10.0,           # 26 MHz: 10 pF (Bluetooth/WiFi common)
    27e6: 10.0,
    32e6: 10.0,
    48e6: 10.0,
}


def _crystal_default_cl(freq_hz: float) -> float | None:
    """Look up typical crystal load capacitance for a given frequency.

    Returns CL in pF or None if frequency is unknown. Uses exact match
    first (within 1% tolerance), then falls back to frequency-band default.
    """
    if not freq_hz or freq_hz <= 0:
        return None
    # Exact match (within 1% tolerance for frequency rounding)
    for table_freq, cl in _CRYSTAL_DEFAULT_CL.items():
        if abs(freq_hz - table_freq) / table_freq < 0.01:
            return cl
    # Broad frequency-band fallback
    if freq_hz <= 100e3:
        return 12.5
    elif freq_hz <= 4e6:
        return 12.5
    elif freq_hz <= 16e6:
        return 18.0
    elif freq_hz <= 30e6:
        return 10.0
    else:
        return 10.0


# ---------------------------------------------------------------------------
# Divider purpose classification
# ---------------------------------------------------------------------------

def _classify_divider_purpose(divider: dict) -> str:
    """Classify a voltage divider's purpose from connected pin names.

    Examines mid_point_connections pin names and the is_feedback flag to
    determine: adc_input, feedback, bias, reference, enable_threshold, or unknown.
    """
    if divider.get("is_feedback"):
        return "feedback"

    mid_pins = divider.get("mid_point_connections", [])
    for mp in mid_pins:
        pn = mp.get("pin_name", "").upper()
        if not pn:
            continue
        # ADC / analog input
        if any(k in pn for k in ("ADC", "AIN", "ANALOG")):
            return "adc_input"
        # Feedback
        if any(k in pn for k in ("FB", "FEEDBACK")):
            return "feedback"
        # Enable / shutdown threshold
        if any(k in pn for k in ("EN", "ENABLE", "SHDN")):
            return "enable_threshold"
        # Comparator / reference / threshold
        if any(k in pn for k in ("COMP", "REF", "THRESH")):
            return "reference"
        # Bias input (opamp, comparator non-inverting/inverting)
        if any(k in pn for k in ("IN+", "IN-", "INP", "INM")):
            return "bias"

    return "unknown"


# ---------------------------------------------------------------------------
# Detectors
# ---------------------------------------------------------------------------

def detect_voltage_dividers(ctx: AnalysisContext) -> dict:
    """Detect voltage dividers and feedback networks.

    Returns dict with keys ``voltage_dividers`` and ``feedback_networks``.
    """
    voltage_dividers: list[dict] = []
    feedback_networks: list[dict] = []

    # ---- Voltage Dividers ----
    # Two resistors in series between different nets, with a mid-point net; parallel
    # resistors on one arm count as one equivalent resistor
    resistors = group_reps(ctx, get_components_by_type(ctx, "resistor", with_parsed_values=True))
    resistor_nets, net_to_resistors = index_two_pin_components(ctx, resistors)

    # Check pairs of resistors that share a net (potential dividers)
    vd_seen = set()  # track (r1, r2) pairs to avoid duplicates
    for net_name, refs in net_to_resistors.items():
        if len(refs) < 2:
            continue
        for i, r1_ref in enumerate(refs):
            r1_n1, r1_n2 = resistor_nets[r1_ref]
            for r2_ref in refs[i + 1:]:
                pair_key = (min(r1_ref, r2_ref), max(r1_ref, r2_ref))
                if pair_key in vd_seen:
                    continue
                vd_seen.add(pair_key)

                r2_n1, r2_n2 = resistor_nets[r2_ref]
                # Looked up per pair: the orientation swap below must not carry into the next pair
                r1 = ctx.comp_lookup[r1_ref]
                r2 = ctx.comp_lookup[r2_ref]

                # Find shared net (mid-point)
                r1_nets = {r1_n1, r1_n2}
                r2_nets = {r2_n1, r2_n2}
                shared = r1_nets & r2_nets
                if len(shared) != 1:
                    continue

                mid_net = shared.pop()
                top_net = (r1_nets - {mid_net}).pop()
                bot_net = (r2_nets - {mid_net}).pop()

                # Reject if mid-point is a power rail with many connections —
                # that's a power bus, not a divider output. Real divider mid-points
                # connect to 2 resistors + maybe an IC input (≤4 connections).
                if ctx.is_power_net(mid_net) or ctx.is_ground(mid_net):
                    mid_pin_count = len(ctx.nets.get(mid_net, {}).get("pins", []))
                    if mid_pin_count > 4:
                        continue

                # Normalize orientation FIRST so the ordering of
                # r1/r2 in the outer loop can't drop valid pairs. If
                # exactly one end is ground, ensure it's bot_net. This
                # subsumes the previous "is_ground(top) and is_power(bot)"
                # swap (a strict subset of this condition) and also
                # catches the unnamed-top-net case that was getting
                # dropped by the ordering-sensitive fall-through.
                if ctx.is_ground(top_net) and not ctx.is_ground(bot_net):
                    top_net, bot_net = bot_net, top_net
                    r1, r2 = r2, r1
                if _divider_is_degenerate(ctx, top_net, bot_net):
                    continue

                # One end should be power, other should be ground (or another power)
                if not (ctx.is_power_net(top_net) and (ctx.is_ground(bot_net) or ctx.is_power_net(bot_net))):
                    # Also catch feedback dividers: output -> mid -> ground.
                    # After the normalization above, an unnamed
                    # top_net with ground bot_net reaches this branch
                    # and passes.
                    if not ctx.is_ground(bot_net):
                        continue

                r1_val = group_value(ctx, r1["reference"])
                r2_val = group_value(ctx, r2["reference"])
                if r1_val <= 0 or r2_val <= 0:
                    continue
                # Extreme ratio → pull-up/pull-down pair, not a real divider.
                # 1000:1 threshold accommodates HV sensing (mains voltage,
                # battery monitoring) where 10M/10K dividers are common.
                if max(r1_val, r2_val) / min(r1_val, r2_val) > 1000:
                    continue

                # Determine which is top/bottom based on net position
                if ctx.is_ground(bot_net):
                    # r_top connects top_net to mid, r_bot connects mid to gnd
                    # Re-derive nets from current r1/r2 (may have been swapped above)
                    r1_nets_cur = set(ctx.get_two_pin_nets(r1["reference"]))
                    if top_net in r1_nets_cur:
                        r_top, r_bot = r1_val, r2_val
                        r_top_ref, r_bot_ref = r1["reference"], r2["reference"]
                    else:
                        r_top, r_bot = r2_val, r1_val
                        r_top_ref, r_bot_ref = r2["reference"], r1["reference"]

                    ratio = r_bot / (r_top + r_bot)

                    divider = {
                        "r_top": group_part(ctx, r_top_ref, "ohms"),
                        "r_bottom": group_part(ctx, r_bot_ref, "ohms"),
                        "top_net": top_net,
                        "mid_net": mid_net,
                        "bottom_net": bot_net,
                        "ratio": round(ratio, 6),
                    }

                    # Check if mid-point connects to a known feedback pin.
                    # NOTE: feedback dividers are intentionally appended to BOTH
                    # `feedback_networks` (for regulator FB matching and feedback-
                    # stability checks) AND `voltage_dividers` (so downstream
                    # consumers — notably `detect_rc_filters` — keep
                    # their exclusion-set correct and don't emit false-positive
                    # RC filters pairing feedback resistors with decoupling caps;
                    # `detect_power_regulators` and `postfilter_vd_and_dedup`
                    # also consume `voltage_dividers` as a shared input).
                    #
                    # Do not dedup the double emission: the exclusion set
                    # `detect_rc_filters` builds from `voltage_dividers` is what
                    # keeps feedback resistors out of RC pairings, and dropping
                    # these entries changes emitted findings that the harness
                    # corpus gate tracks. Coordinate with the harness before
                    # changing it.
                    arm_refs = group_members(ctx, r_top_ref) + group_members(ctx, r_bot_ref)
                    # The arms and any DNP part beside them are not mid-point connections
                    groups = parallel_groups(ctx, "resistor")
                    arm_nets = {groups[r]["nets"] for r in (r_top_ref, r_bot_ref) if r in groups}
                    if mid_net in ctx.nets:
                        mid_pins = [p for p in ctx.nets[mid_net]["pins"]
                                    if p["component"] not in arm_refs
                                    and groups.get(p["component"], {}).get("nets") not in arm_nets
                                    and not p["component"].startswith("#")]
                        if mid_pins:
                            divider["mid_point_connections"] = mid_pins
                            # If connected to an IC FB pin, this is likely a feedback network
                            for mp in mid_pins:
                                if "FB" in mp.get("pin_name", "").upper():
                                    divider["is_feedback"] = True
                                    divider["detector"] = "detect_voltage_dividers"
                                    divider["rule_id"] = "VD-DET"
                                    divider["category"] = "voltage_dividers"
                                    divider["severity"] = "info"
                                    divider["confidence"] = "deterministic"
                                    divider["evidence_source"] = "topology"
                                    divider["summary"] = f"Voltage divider {r_top_ref}/{r_bot_ref}"
                                    divider["description"] = "Feedback network voltage divider detected"
                                    divider["components"] = arm_refs
                                    divider["nets"] = []
                                    divider["pins"] = []
                                    divider["recommendation"] = ""
                                    divider["report_context"] = {"section": "Voltage Dividers", "impact": "", "standard_ref": ""}
                                    divider["provenance"] = make_provenance("vd_two_resistor", "deterministic", [r_top_ref, r_bot_ref])
                                    feedback_networks.append(divider)
                                    break

                    # Classify divider purpose from connected pin names
                    divider["purpose"] = _classify_divider_purpose(divider)
                    divider["detector"] = "detect_voltage_dividers"
                    divider["rule_id"] = "VD-DET"
                    divider["category"] = "voltage_dividers"
                    divider["severity"] = "info"
                    divider["confidence"] = "deterministic"
                    divider["evidence_source"] = "topology"
                    divider["summary"] = f"Voltage divider {r_top_ref}/{r_bot_ref}"
                    divider["description"] = "Resistive voltage divider detected"
                    divider["components"] = arm_refs
                    divider["nets"] = []
                    divider["pins"] = []
                    divider["recommendation"] = ""
                    divider["report_context"] = {"section": "Voltage Dividers", "impact": "", "standard_ref": ""}
                    divider["provenance"] = make_provenance("vd_two_resistor", "deterministic", [r_top_ref, r_bot_ref])

                    voltage_dividers.append(divider)

    return {"voltage_dividers": voltage_dividers, "feedback_networks": feedback_networks}


def _divider_is_degenerate(ctx: AnalysisContext, top_net: str, bot_net: str) -> bool:
    """Both ends on one net, or both on ground: no voltage across the divider."""
    return top_net == bot_net or (ctx.is_ground(top_net) and ctx.is_ground(bot_net))


def _chain_link(ctx: AnalysisContext, ref: str, ohms: float) -> dict:
    link = {"ref": ref, "ohms": ohms}
    members = group_members(ctx, ref)
    if len(members) > 1:
        link["parallel_refs"] = members
    return link


def _merge_series_dividers(voltage_dividers: list[dict], ctx: AnalysisContext) -> list[dict]:
    """Merge series resistors in voltage divider chains.

    When a divider's top_net or bottom_net is a pass-through node (connects
    to exactly 2 resistors and no IC/active pins), extend the chain through
    it, combining series resistances.
    """
    # Build resistor-net index (one entry per parallel group)
    all_resistors = group_reps(ctx, get_components_by_type(ctx, "resistor", with_parsed_values=True))
    resistor_nets, net_to_resistors = index_two_pin_components(ctx, all_resistors)

    # An IC placed without its pins (an unresolved legacy symbol) may sit on any net.
    all_ic_pins_known = all(ctx.ref_pins.get(c["reference"]) for c in ctx.components
                            if c.get("type") == "ic")

    def _local_label_only(net_name):
        """Named only by local labels (no power symbol, no global or hierarchical label),
        so every pin of the net is on this sheet."""
        info = ctx.nets.get(net_name)
        if (not info or not all_ic_pins_known or net_name in ctx.known_power_rails
                or net_name in ctx.topology_rails):
            return False
        return {lbl.get("type") for lbl in info.get("labels") or []} == {"label"}

    def _is_passthrough(net_name):
        """A pass-through node connects exactly 2 resistors (a parallel group counts once)
        and no active components. A node named like a rail (12V_FBM) passes only when local
        labels alone name it."""
        if ctx.is_ground(net_name):
            return False
        if ctx.is_power_net(net_name) and not _local_label_only(net_name):
            return False
        r_at_net = net_to_resistors.get(net_name, [])
        if len(r_at_net) != 2:
            return False
        if net_name not in ctx.nets:
            return True
        for p in ctx.nets[net_name]["pins"]:
            comp = ctx.comp_lookup.get(p["component"])
            if comp and comp["type"] not in ("resistor",):
                return False
        return True

    def _extend_chain(start_ref, into_net):
        """Follow series resistors through pass-through nodes.
        Returns [(ref, ohms), ...] of additional resistors and the final net."""
        extra = []
        cur_ref = start_ref
        cur_net = into_net
        while _is_passthrough(cur_net):
            others = [r for r in net_to_resistors.get(cur_net, []) if r != cur_ref]
            if len(others) != 1:
                break
            nxt = others[0]
            if group_value(ctx, nxt) is None:
                break
            extra.append((nxt, group_value(ctx, nxt)))
            n1, n2 = resistor_nets[nxt]
            cur_net = n2 if n1 == cur_net else n1
            cur_ref = nxt
        return extra, cur_net

    result = []
    chain_member_refs = set()

    for vd in voltage_dividers:
        r_top_ref = vd["r_top"]["ref"]
        r_bot_ref = vd["r_bottom"]["ref"]

        # Extend top chain through top_net
        top_extra, new_top_net = _extend_chain(r_top_ref, vd["top_net"])
        # Extend bottom chain through bottom_net
        bot_extra, new_bot_net = _extend_chain(r_bot_ref, vd["bottom_net"])

        if not top_extra and not bot_extra:
            result.append(vd)
            continue
        if _divider_is_degenerate(ctx, new_top_net, new_bot_net):
            # The chain closes on the other arm's end: a parallel leg, not a divider.
            # The pipeline drops the same record from feedback_networks.
            vd["_closed_chain"] = True
            continue

        new_vd = dict(vd)

        if top_extra:
            all_top = [(r_top_ref, vd["r_top"]["ohms"])] + top_extra
            total_top = sum(o for _, o in all_top)
            new_vd["r_top"] = dict(vd["r_top"])
            new_vd["r_top"]["ohms"] = total_top
            new_vd["r_top"]["chain_resistors"] = [_chain_link(ctx, r, o) for r, o in all_top]
            new_vd["top_net"] = new_top_net
            for r, _ in all_top:
                chain_member_refs.add(r)

        if bot_extra:
            all_bot = [(r_bot_ref, vd["r_bottom"]["ohms"])] + bot_extra
            total_bot = sum(o for _, o in all_bot)
            new_vd["r_bottom"] = dict(vd["r_bottom"])
            new_vd["r_bottom"]["ohms"] = total_bot
            new_vd["r_bottom"]["chain_resistors"] = [_chain_link(ctx, r, o) for r, o in all_bot]
            new_vd["bottom_net"] = new_bot_net
            for r, _ in all_bot:
                chain_member_refs.add(r)

        # Recalculate ratio
        r_t = new_vd["r_top"]["ohms"]
        r_b = new_vd["r_bottom"]["ohms"]
        if r_t + r_b > 0:
            new_vd["ratio"] = round(r_b / (r_t + r_b), 6)

        result.append(new_vd)

    # Mark sub-pair dividers whose resistors are all part of a chain
    for vd in result:
        if "chain_resistors" in vd.get("r_top", {}) or "chain_resistors" in vd.get("r_bottom", {}):
            continue  # This IS the chain divider
        if vd["r_top"]["ref"] in chain_member_refs and vd["r_bottom"]["ref"] in chain_member_refs:
            vd["suppressed_by_chain"] = True

    return result


def _merged_caps(ctx: AnalysisContext, cap_refs: list[str], farads: float) -> dict:
    """Capacitor dict for caps merged on one filter node; ``parallel_refs`` only when
    every cap shares both nets with the first."""
    part = {"ref": cap_refs[0], "value": f"{len(cap_refs)} caps parallel", "farads": farads}
    nets = {frozenset(ctx.get_two_pin_nets(r)) for r in cap_refs}
    if len(nets) == 1:
        part["parallel_refs"] = cap_refs
    part["parallel_caps"] = cap_refs
    return part


def _feeds_inputs_only(ctx: AnalysisContext, net_name: str, ref: str) -> bool:
    """Besides *ref* and capacitors, the net holds only IC input pins, at least one.

    A second resistor (an op-amp feedback leg, a bias resistor) means the node is not
    a plain filtered input."""
    found = False
    for p in ctx.nets.get(net_name, {}).get("pins", []):
        if p["component"].startswith("#") or p["component"] == ref:
            continue
        comp_type = (ctx.comp_lookup.get(p["component"]) or {}).get("type")
        if comp_type == "capacitor":
            continue
        if comp_type != "ic" or str(p.get("pin_type") or "").split("+")[0] != "input":
            return False
        found = True
    return found


def detect_rc_filters(ctx: AnalysisContext, voltage_dividers: list[dict],
                      crystal_circuits: list[dict] | None = None,
                      opamp_circuits: list[dict] | None = None) -> list[dict]:
    """Detect RC filters. Takes voltage_dividers/crystal_circuits/opamp_circuits to exclude."""
    results_rc: list[dict] = []

    # A potentiometer on three distinct nets is not a two-terminal filter resistor; one
    # wired as a rheostat (two of its pins on one net) is.
    resistors = [r for r in group_reps(ctx, get_components_by_type(ctx, "resistor", with_parsed_values=True))
                 if not _is_three_net_pot(ctx, r["reference"])]
    resistor_nets, _ = index_two_pin_components(ctx, resistors)
    for r in resistors:
        rheostat_nets = _part_nets(ctx, r["reference"])
        if _is_potentiometer(ctx, r["reference"]) and len(rheostat_nets) == 2:
            resistor_nets[r["reference"]] = tuple(rheostat_nets)

    # ---- RC Filters ----
    # R and C must share a SIGNAL net (not power/ground) to form a real filter.
    # If they only share GND, every R and C in the circuit would match.
    # Exclude resistors that are part of voltage dividers — pairing a feedback
    # divider resistor with an output decoupling cap is a common false positive.
    # Several top resistors that share one bottom resistor meet at a junction, and only one
    # of them feeds the divider. A top resistor whose far end holds nothing but caps and IC
    # inputs is a load on the junction, not the feed, so a cap on that far end still forms a filter
    # with it. A cap on the junction itself sees every resistor there and stays excluded.
    bottom_uses: dict[tuple[str, str], int] = {}
    for vd in voltage_dividers:
        key = (vd["mid_net"], vd["r_bottom"]["ref"])
        bottom_uses[key] = bottom_uses.get(key, 0) + 1
    vd_resistor_refs = set()
    junction_nets: dict[str, set[str]] = {}  # junction load resistor -> its junction nets
    for vd in voltage_dividers:
        load = (bottom_uses[(vd["mid_net"], vd["r_bottom"]["ref"])] > 1
                and not vd.get("is_feedback")
                and "chain_resistors" not in vd["r_top"]
                and _feeds_inputs_only(ctx, vd["top_net"], vd["r_top"]["ref"]))
        for arm in ("r_top", "r_bottom"):
            refs = [vd[arm]["ref"], *vd[arm].get("parallel_refs", ())]
            if arm == "r_top" and load:
                for ref in refs:
                    junction_nets.setdefault(ref, set()).add(vd["mid_net"])
            else:
                vd_resistor_refs.update(refs)

    # Exclude opamp feedback resistors, capacitors, and input resistors
    opamp_exclude_refs = set()
    for oa in (opamp_circuits or []):
        fb_r = oa.get("feedback_resistor")
        if isinstance(fb_r, dict):
            opamp_exclude_refs.add(fb_r.get("ref", ""))
        fb_c = oa.get("feedback_capacitor")
        if isinstance(fb_c, dict):
            opamp_exclude_refs.add(fb_c.get("ref", ""))
        inp_r = oa.get("input_resistor")
        if isinstance(inp_r, dict):
            opamp_exclude_refs.add(inp_r.get("ref", ""))
    opamp_exclude_refs.discard("")

    # Exclude crystal circuit components (load caps + feedback resistors)
    crystal_refs = set()
    for xtal in (crystal_circuits or []):
        crystal_refs.add(xtal.get("reference", ""))
        for lc in xtal.get("load_caps", []):
            crystal_refs.add(lc["ref"])
        fb = xtal.get("feedback_resistor")
        if isinstance(fb, dict):
            crystal_refs.add(fb.get("ref", ""))
        elif isinstance(fb, str) and fb:
            crystal_refs.add(fb)

    capacitors = group_reps(ctx, get_components_by_type(ctx, "capacitor", with_parsed_values=True))
    cap_nets, net_to_caps = index_two_pin_components(ctx, capacitors)

    def _in(refs: set[str], ref: str) -> bool:
        return any(m in refs for m in group_members(ctx, ref))

    # Track seen R-C pairs to prevent bidirectional duplicates
    seen_rc_pairs: set[frozenset[str]] = set()
    rc_shared_nets: list[str] = []  # the R-C node of each results_rc entry

    for res in resistors:
        if _in(vd_resistor_refs, res["reference"]):
            continue  # Skip voltage divider resistors
        if _in(crystal_refs, res["reference"]):
            continue  # Skip crystal circuit components
        if _in(opamp_exclude_refs, res["reference"]):
            continue  # Skip opamp feedback/input resistors
        if res["reference"] not in resistor_nets:
            continue
        r_n1, r_n2 = resistor_nets[res["reference"]]
        r_nets = {r_n1, r_n2}

        # Only check capacitors that share a net with this resistor
        candidate_caps = set()
        for rn in (r_n1, r_n2):
            if not ctx.is_power_net(rn) and not ctx.is_ground(rn):
                for cref in net_to_caps.get(rn, ()):
                    candidate_caps.add(cref)

        for cap_ref in sorted(candidate_caps):
            if _in(crystal_refs, cap_ref):
                continue  # Skip crystal circuit components
            if _in(opamp_exclude_refs, cap_ref):
                continue  # Skip opamp feedback capacitors

            # Skip if this R-C pair was already found from the other direction
            rc_pair = frozenset((res["reference"], cap_ref))
            if rc_pair in seen_rc_pairs:
                continue

            c_n1, c_n2 = cap_nets[cap_ref]
            c_nets = {c_n1, c_n2}

            shared = r_nets & c_nets
            if len(shared) != 1:
                continue

            shared_net = shared.pop()
            if shared_net in junction_nets.get(res["reference"], ()):
                continue

            # The shared net must NOT be a power/ground rail — those create
            # false matches between every R and C on the board.
            if ctx.is_power_net(shared_net) or ctx.is_ground(shared_net):
                continue

            # Reject if shared net has too many non-passive connections.
            # A real RC filter node typically has 2-3 connections (R + C +
            # maybe one IC pin).  On high-fanout nets, accept if most
            # connections are passives (filter node with parallel caps),
            # reject if many ICs are connected (bus/data line).
            shared_pin_count = len(ctx.nets.get(shared_net, {}).get("pins", []))
            if shared_pin_count > 6:
                if ctx.nq:
                    non_passive = sum(
                        1 for c in ctx.nq.components_on_net(shared_net)
                        if c["type"] not in ("resistor", "capacitor", "inductor"))
                    if non_passive > 3:
                        continue
                else:
                    continue

            r_other = (r_nets - {shared_net}).pop()
            c_other = (c_nets - {shared_net}).pop()

            # Skip if R and C non-shared ends are the same net —
            # output==ground is logically impossible for a filter
            if r_other == c_other:
                continue

            r_val = group_value(ctx, res["reference"])
            c_val = group_value(ctx, cap_ref)

            # Skip pairs where R or C has no valid value (None or zero) — a
            # 0-ohm resistor or unparsed capacitor is not a filter.
            if not r_val or not c_val:
                continue

            # EQ-020: f_c = 1/(2πRC) (RC filter cutoff frequency)
            if r_val > 0 and c_val > 0:
                fc = 1.0 / (2.0 * math.pi * r_val * c_val)
                tau = r_val * c_val

                # Classify filter type
                if ctx.is_ground(c_other):
                    filter_type = "low-pass"
                elif ctx.is_ground(r_other):
                    filter_type = "high-pass"
                else:
                    filter_type = "RC-network"

                # Skip if R is very small — likely series termination or current
                # sense shunt, not an intentional filter
                if r_val < 10:
                    continue

                # High-pass: C in series from the source, R from the R-C node to ground.
                if filter_type == "low-pass":
                    in_net, out_net = r_other, shared_net
                elif filter_type == "high-pass":
                    in_net, out_net = c_other, shared_net
                else:
                    in_net, out_net = shared_net, r_other
                rc_entry = {
                    "type": filter_type,
                    "resistor": group_part(ctx, res["reference"], "ohms"),
                    "capacitor": group_part(ctx, cap_ref, "farads"),
                    "cutoff_hz": round(fc, 2),
                    "time_constant_s": tau,
                    "input_net": in_net,
                    "output_net": out_net,
                    # Use c_other as ground if it IS ground, else use
                    # r_other only if it IS ground; otherwise report c_other
                    # (the capacitor's far end) to avoid output==ground
                    "ground_net": c_other if ctx.is_ground(c_other) else (
                        r_other if ctx.is_ground(r_other) else c_other),
                }

                rc_entry["cutoff_formatted"] = _format_frequency(fc)
                rc_entry["detector"] = "detect_rc_filters"
                rc_entry["rule_id"] = "RC-DET"
                rc_entry["category"] = "passive_filters"
                rc_entry["severity"] = "info"
                rc_entry["confidence"] = "deterministic"
                rc_entry["evidence_source"] = "topology"
                rc_entry["summary"] = f"RC filter {res['reference']}/{cap_ref} at {round(fc, 2)}Hz"
                rc_entry["description"] = f"{filter_type} RC filter"
                rc_entry["components"] = group_members(ctx, res["reference"]) + group_members(ctx, cap_ref)
                rc_entry["nets"] = []
                rc_entry["pins"] = []
                rc_entry["recommendation"] = ""
                rc_entry["report_context"] = {"section": "Passive Filters", "impact": "", "standard_ref": ""}
                rc_entry["provenance"] = make_provenance("rc_topology", "deterministic", [res["reference"], cap_ref])

                seen_rc_pairs.add(rc_pair)
                results_rc.append(rc_entry)
                rc_shared_nets.append(shared_net)

    # Merge RC filters where the same resistor pairs with multiple caps on
    # the same shared net (parallel caps = one effective filter, not N filters).
    _rc_groups: dict[tuple[str, str, str, str], list[dict]] = {}
    for rc, shared_net in zip(results_rc, rc_shared_nets):
        key = (rc["resistor"]["ref"], rc.get("input_net", ""), rc.get("output_net", ""), shared_net)
        _rc_groups.setdefault(key, []).append(rc)
    merged_rc: list[dict] = []
    for key, entries in _rc_groups.items():
        if len(entries) == 1:
            merged_rc.append(entries[0])
        else:
            total_c = sum(e["capacitor"]["farads"] for e in entries)
            r_val = entries[0]["resistor"]["ohms"]
            fc = 1.0 / (2.0 * math.pi * r_val * total_c)
            tau = r_val * total_c
            cap_refs = [m for e in entries for m in e["capacitor"].get("parallel_refs", [e["capacitor"]["ref"]])]
            base = entries[0].copy()
            base["capacitor"] = _merged_caps(ctx, cap_refs, total_c)
            base["cutoff_hz"] = round(fc, 2)
            base["time_constant_s"] = tau
            base["cutoff_formatted"] = _format_frequency(fc)
            base["summary"] = f"RC filter {base['resistor']['ref']}/{cap_refs[0]} at {round(fc, 2)}Hz"
            base["components"] = group_members(ctx, base["resistor"]["ref"]) + cap_refs
            merged_rc.append(base)
    return merged_rc


def detect_lc_filters(ctx: AnalysisContext) -> list[dict]:
    """Detect LC filters."""
    capacitors = group_reps(ctx, get_components_by_type(ctx, "capacitor", with_parsed_values=True))
    inductors = group_reps(ctx, get_components_by_type(ctx, ("inductor", "ferrite_bead"), with_parsed_values=True))

    # Collect LC pairs grouped by (inductor, shared_net). Multiple caps on
    # the same inductor output node are parallel decoupling, not separate
    # filters — merge them into one entry with summed capacitance.
    _lc_groups: dict[tuple[str, str], list[dict]] = {}

    for ind in inductors:
        # Skip ferrite beads — they're impedance devices, not filter inductors
        lib_id = ind.get("lib_id", "").lower()
        val_lower = ind.get("value", "").lower()
        if (ind.get("type") == "ferrite_bead"
                or "ferrite" in lib_id or "bead" in lib_id
                or "ferrite" in val_lower or "bead" in val_lower):
            continue
        l_n1, l_n2 = ctx.get_two_pin_nets(ind["reference"])
        if not l_n1 or not l_n2:
            continue

        for cap in capacitors:
            c_n1, c_n2 = ctx.get_two_pin_nets(cap["reference"])
            if not c_n1 or not c_n2:
                continue

            l_nets = {l_n1, l_n2}
            c_nets = {c_n1, c_n2}
            # Skip components with both pins on the same net (shorted)
            if len(l_nets) < 2 or len(c_nets) < 2:
                continue
            shared = l_nets & c_nets
            if len(shared) != 1:
                continue

            shared_net_lc = shared.pop()
            # Skip if shared net is power/ground (would match all L-C pairs)
            if ctx.is_power_net(shared_net_lc) or ctx.is_ground(shared_net_lc):
                continue

            # Skip high-fanout shared nets — in RF designs, impedance
            # matching networks share nets with many L/C components. Real LC
            # filters have 2-4 connections at the junction node.
            shared_pin_count = len(ctx.nets.get(shared_net_lc, {}).get("pins", []))
            if shared_pin_count > 6:
                if ctx.nq:
                    non_passive = sum(
                        1 for c in ctx.nq.components_on_net(shared_net_lc)
                        if c["type"] not in ("resistor", "capacitor", "inductor"))
                    if non_passive > 3:
                        continue
                else:
                    continue

            # Skip bootstrap capacitors: cap between BST/BOOT pin and SW/LX node.
            # These are gate-drive charge pumps, not signal filters.
            cap_other_net = (c_nets - {shared_net_lc}).pop()
            is_bootstrap = False
            if cap_other_net and cap_other_net in ctx.nets:
                for p in ctx.nets[cap_other_net]["pins"]:
                    pn = p.get("pin_name", "").upper().rstrip("0123456789").rstrip("_")
                    pn_parts = {pp.strip() for pp in pn.split("/")}
                    if pn_parts & _BOOTSTRAP_PIN_TOKENS:
                        is_bootstrap = True
                        break
            if is_bootstrap:
                continue

            l_val = group_value(ctx, ind["reference"])
            c_val = group_value(ctx, cap["reference"])

            if l_val > 0 and c_val > 0:
                # EQ-021: f₀ = 1/(2π√(LC)) (LC resonant frequency)
                f0 = 1.0 / (2.0 * math.pi * math.sqrt(l_val * c_val))
                # EQ-022: Z₀ = √(L/C) (LC characteristic impedance)
                z0 = math.sqrt(l_val / c_val)  # characteristic impedance

                lc_entry = {
                    "inductor": group_part(ctx, ind["reference"], "henries"),
                    "capacitor": group_part(ctx, cap["reference"], "farads"),
                    "resonant_hz": round(f0, 2),
                    "impedance_ohms": round(z0, 2),
                    "shared_net": shared_net_lc,
                }

                lc_entry["resonant_formatted"] = _format_frequency(f0)
                lc_entry["detector"] = "detect_lc_filters"
                lc_entry["rule_id"] = "LC-DET"
                lc_entry["category"] = "passive_filters"
                lc_entry["severity"] = "info"
                lc_entry["confidence"] = "deterministic"
                lc_entry["evidence_source"] = "topology"
                lc_entry["summary"] = f"LC filter at {round(f0, 2)}Hz"
                lc_entry["description"] = ("LC filter with parallel capacitors" if "parallel_refs" in lc_entry["capacitor"]
                                           else "LC filter or resonant network detected")
                lc_entry["components"] = group_members(ctx, ind["reference"]) + group_members(ctx, cap["reference"])
                lc_entry["nets"] = []
                lc_entry["pins"] = []
                lc_entry["recommendation"] = ""
                lc_entry["report_context"] = {"section": "Passive Filters", "impact": "", "standard_ref": ""}
                lc_entry["provenance"] = make_provenance("lc_topology", "deterministic", lc_entry["components"])

                cap_other_net_for_group = (c_nets - {shared_net_lc}).pop()
                _lc_groups.setdefault((ind["reference"], shared_net_lc, cap_other_net_for_group), []).append(lc_entry)

    # Merge parallel caps per inductor-net pair
    lc_filters: list[dict] = []
    for (_ind_ref, _shared_net, _other_net), entries in _lc_groups.items():
        # Deduplicate caps by reference (multi-project schematics
        # can have multiple components sharing the same reference designator)
        seen_refs = set()
        deduped = []
        for e in entries:
            cref = e["capacitor"]["ref"]
            if cref not in seen_refs:
                seen_refs.add(cref)
                deduped.append(e)
        entries = deduped

        if len(entries) == 1:
            lc_filters.append(entries[0])
        else:
            total_c = sum(e["capacitor"]["farads"] for e in entries)
            l_val = entries[0]["inductor"]["henries"]
            f0 = 1.0 / (2.0 * math.pi * math.sqrt(l_val * total_c))
            z0 = math.sqrt(l_val / total_c)
            cap_refs = [m for e in entries for m in e["capacitor"].get("parallel_refs", [e["capacitor"]["ref"]])]
            merged = {
                "inductor": entries[0]["inductor"],
                "capacitor": _merged_caps(ctx, cap_refs, total_c),
                "resonant_hz": round(f0, 2),
                "impedance_ohms": round(z0, 2),
                "shared_net": _shared_net,
            }
            merged["resonant_formatted"] = _format_frequency(f0)
            merged["detector"] = "detect_lc_filters"
            merged["rule_id"] = "LC-DET"
            merged["category"] = "passive_filters"
            merged["severity"] = "info"
            merged["confidence"] = "deterministic"
            merged["evidence_source"] = "topology"
            merged["summary"] = f"LC filter at {round(f0, 2)}Hz"
            merged["description"] = "LC filter with parallel capacitors"
            merged["components"] = group_members(ctx, entries[0]["inductor"]["ref"]) + cap_refs
            merged["nets"] = []
            merged["pins"] = []
            merged["recommendation"] = ""
            merged["report_context"] = {"section": "Passive Filters", "impact": "", "standard_ref": ""}
            merged["provenance"] = make_provenance("lc_topology", "deterministic", [entries[0]["inductor"]["ref"]] + cap_refs)
            lc_filters.append(merged)

    # Suppress overcounting — if one inductor pairs with caps on BOTH
    # its nets, it's likely an RF impedance matching network, not separate LC
    # filters. Keep at most 1 entry per inductor net (the largest capacitance).
    from collections import defaultdict
    _ind_nets: dict[str, set[str]] = defaultdict(set)
    for f in lc_filters:
        _ind_nets[f["inductor"]["ref"]].add(f["shared_net"])
    # Inductors with caps on both nets → matching network
    _match_inductors = {ref for ref, nets in _ind_nets.items() if len(nets) >= 2}
    if _match_inductors:
        keep: list[dict] = []
        # Group by (inductor, shared_net), keep only the largest cap entry
        _best: dict[tuple[str, str], dict] = {}
        for f in lc_filters:
            iref = f["inductor"]["ref"]
            if iref not in _match_inductors:
                keep.append(f)
                continue
            key = (iref, f["shared_net"])
            if key not in _best or f["capacitor"]["farads"] > _best[key]["capacitor"]["farads"]:
                _best[key] = f
        keep.extend(_best.values())
        lc_filters = keep

    return lc_filters


def _load_legs(load_caps: list[dict]) -> list[float]:
    """Load capacitance per oscillator leg (net), legs in first-seen order."""
    legs: dict[str, float] = {}
    seen: set[str] = set()
    for lc in load_caps:
        if lc["ref"] not in seen:
            seen.add(lc["ref"])
            legs[lc["net"]] = legs.get(lc["net"], 0.0) + lc["farads"]
    return list(legs.values())


def _dnp_cap_beside_fitted(ctx: AnalysisContext, ref: str) -> bool:
    return parallel_groups(ctx, "capacitor").get(ref, {}).get("excluded", False)


def detect_crystal_circuits(ctx: AnalysisContext) -> list[dict]:
    """Detect crystal oscillator circuits."""
    crystal_circuits: list[dict] = []
    crystals = [c for c in ctx.components if c["type"] == "crystal"]
    for xtal in crystals:
        xtal_pins = xtal.get("pins", [])
        if len(xtal_pins) < 2:
            continue

        # Skip active oscillators (>=4 pins with a VCC/VDD power pin)
        # They should be handled by the active oscillator section below
        if len(xtal_pins) >= 4:
            has_power_pin = False
            for pin in xtal_pins:
                pn_upper = pin.get("name", "").upper()
                if any(kw in pn_upper for kw in ("VCC", "VDD", "V+")):
                    has_power_pin = True
                    break
                net_name, _ = ctx.pin_net.get((xtal["reference"], pin["number"]), (None, None))
                if net_name and ctx.is_power_net(net_name) and not ctx.is_ground(net_name):
                    has_power_pin = True
                    break
            if has_power_pin:
                continue

        # Find capacitors connected to crystal signal pins (not power/ground)
        xtal_nets = set()
        for pin in xtal_pins:
            net_name, _ = ctx.pin_net.get((xtal["reference"], pin["number"]), (None, None))
            if net_name and not ctx.is_power_net(net_name) and not ctx.is_ground(net_name):
                xtal_nets.add(net_name)

        load_caps = []
        for net_name in sorted(xtal_nets):
            if net_name not in ctx.nets:
                continue
            for p in ctx.nets[net_name]["pins"]:
                if (p["component"] != xtal["reference"]
                        and ctx.comp_lookup.get(p["component"], {}).get("type") == "capacitor"
                        and not _dnp_cap_beside_fitted(ctx, p["component"])):
                    cap_ref = p["component"]
                    cap_val = ctx.parsed_values.get(cap_ref)
                    if cap_val:
                        # Check if other end of cap goes to ground
                        cap_n1, cap_n2 = ctx.get_two_pin_nets(cap_ref)
                        other_net = cap_n2 if cap_n1 == net_name else cap_n1
                        if ctx.is_ground(other_net):
                            load_caps.append({
                                "ref": cap_ref,
                                "value": ctx.comp_lookup[cap_ref]["value"],
                                "farads": cap_val,
                                "net": net_name,
                            })

        xtal_entry = {
            "reference": xtal["reference"],
            "value": xtal.get("value", ""),
            "frequency": _parse_crystal_frequency(xtal.get("value", "")),
            "load_caps": load_caps,
        }

        # Compute effective load capacitance: CL = (C1 * C2) / (C1 + C2) + C_stray,
        # C1 and C2 the total capacitance on each leg (Pierce load, ST AN2867)
        legs = _load_legs(load_caps)
        if len(legs) >= 2:
            c1, c2 = legs[0], legs[1]
            c_stray = 3e-12  # typical stray capacitance estimate
            cl_eff = (c1 * c2) / (c1 + c2) + c_stray
            xtal_entry["effective_load_pF"] = round(cl_eff * 1e12, 2)
            if len(legs) == len(load_caps):
                xtal_entry["note"] = f"CL_eff = ({load_caps[0]['value']} * {load_caps[1]['value']}) / ({load_caps[0]['value']} + {load_caps[1]['value']}) + ~3pF stray"
            else:
                xtal_entry["note"] = (f"CL_eff = ({c1 * 1e12:g}pF * {c2 * 1e12:g}pF) / ({c1 * 1e12:g}pF + {c2 * 1e12:g}pF)"
                                      f" + ~3pF stray (load capacitance summed per leg)")

        # Crystal load capacitance validation
        target_load_pF = None
        target_load_source = None
        xtal_value = xtal.get("value", "")
        # Probe datasheet first (highest authority): facts.crystal.load_capacitance.
        # DatasheetFacts has no `crystal` category, so _cl_specs is always None
        # and the value-string parse and default below decide the target.
        _cache_dir = getattr(ctx, 'cache_dir', None)
        _xtal_mpn = xtal.get('mpn') or xtal.get('value') or ''
        _xtal_facts = get_facts(_xtal_mpn, cache_dir=_cache_dir, diagnostics=getattr(ctx, "diagnostics", None)) if _xtal_mpn else None
        _cl_specs = getattr(getattr(_xtal_facts, 'crystal', None), 'load_capacitance', None)
        if has_data(_cl_specs):
            _cl_sv = best(_cl_specs, min_confidence='medium')
            if _cl_sv is not None and _cl_sv.typ is not None:
                target_load_pF = _cl_sv.typ * 1e12  # Farads → pF
                target_load_source = "datasheet"
        # Try parsing from value string: "16MHz/18pF", "8MHz 20pF"
        if target_load_pF is None:
            load_match = re.search(r'(\d+\.?\d*)\s*pF', xtal_value, re.IGNORECASE)
            if load_match:
                target_load_pF = float(load_match.group(1))
                target_load_source = "parsed_from_value"
        # Frequency-based defaults — use granular lookup table
        if target_load_pF is None:
            freq = xtal_entry.get("frequency")
            if freq:
                target_load_pF = _crystal_default_cl(freq)
                if target_load_pF is not None:
                    target_load_source = "frequency_default"
        xtal_entry["target_load_pF"] = target_load_pF
        xtal_entry["target_load_source"] = target_load_source
        if target_load_pF and "effective_load_pF" in xtal_entry:
            error_pct = (xtal_entry["effective_load_pF"] - target_load_pF) / target_load_pF * 100
            xtal_entry["load_cap_error_pct"] = round(error_pct, 1)
            if target_load_source == "frequency_default":
                # Target is a statistical default, not from the actual crystal
                # datasheet. Don't report as out_of_spec — the default itself
                # may be wrong for this specific crystal part.
                if abs(error_pct) <= 10:
                    xtal_entry["load_cap_status"] = "ok"
                else:
                    xtal_entry["load_cap_status"] = "unverified"
            else:
                # Target is parsed from the crystal value string or datasheet —
                # high confidence, use normal thresholds.
                if abs(error_pct) <= 10:
                    xtal_entry["load_cap_status"] = "ok"
                elif abs(error_pct) <= 25:
                    xtal_entry["load_cap_status"] = "marginal"
                else:
                    xtal_entry["load_cap_status"] = "out_of_spec"

        _xtal_freq = xtal_entry.get("frequency")
        _xtal_freq_str = f" at {_xtal_freq}Hz" if _xtal_freq else ""
        xtal_entry["detector"] = "detect_crystal_circuits"
        xtal_entry["rule_id"] = "XL-DET"
        xtal_entry["category"] = "timing"
        xtal_entry["severity"] = "info"
        xtal_entry["confidence"] = "deterministic"
        xtal_entry["evidence_source"] = "topology"
        xtal_entry["summary"] = f"Crystal {xtal['reference']}{_xtal_freq_str}"
        xtal_entry["description"] = "Crystal oscillator circuit detected"
        xtal_entry["components"] = [xtal["reference"]]
        xtal_entry["nets"] = []
        xtal_entry["pins"] = []
        xtal_entry["recommendation"] = ""
        xtal_entry["report_context"] = {"section": "Timing", "impact": "", "standard_ref": ""}
        xtal_entry["provenance"] = make_provenance(
            "xtal_passive_caps", "deterministic",
            [xtal["reference"]] + [lc["ref"] for lc in load_caps])

        crystal_circuits.append(xtal_entry)

    # Detect active oscillators (TCXO, VCXO, MEMS, etc.)
    _osc_keywords = ("oscillator", "tcxo", "vcxo", "mems_osc", "sit2", "sit8",
                     "dsc6", "dsc1", "sg-", "asfl", "asco", "asdm", "fox",
                     "ecs-", "abracon")
    for comp in ctx.components:
        if comp["type"] == "oscillator":
            pass  # always include
        elif comp["type"] in ("crystal", "ic"):
            val_lower = comp.get("value", "").lower()
            lib_lower = comp.get("lib_id", "").lower()
            if not any(kw in val_lower or kw in lib_lower for kw in _osc_keywords):
                continue
            # Exclude RF/analog ICs that happen to match oscillator keywords
            _osc_exclude = ("switch", "mux", "balun", "filter", "amplifier", "lna",
                            "driver", "mixer", "attenuator", "diplexer", "splitter",
                            "spdt", "sp3t", "sp4t", "74lvc", "74hc")
            if any(kw in val_lower or kw in lib_lower for kw in _osc_exclude):
                continue
            # Skip if already detected as a passive crystal
            if any(xc["reference"] == comp["reference"] for xc in crystal_circuits):
                continue
        else:
            continue

        ref = comp["reference"]
        # Find output net (clock output pin)
        out_net = None
        vcc_net = None
        for pin in comp.get("pins", []):
            net_name, _ = ctx.pin_net.get((ref, pin["number"]), (None, None))
            if not net_name:
                continue
            pname = pin.get("name", "").upper()
            if pname in ("OUT", "OUTPUT", "CLK", "CLKOUT"):
                out_net = net_name
            elif ctx.is_power_net(net_name) and not ctx.is_ground(net_name):
                vcc_net = net_name
        # do NOT fall back to the first non-power/non-ground pin as
        # output_net — on a misclassified bus peripheral that net is a data
        # line (e.g. I2C SCL), not a clock output. Leave out_net unset when
        # no clock-out-named pin is present; CD-DET phase 2 already skips
        # entries with no output_net.

        _osc_freq = _parse_crystal_frequency(comp.get("value", ""))
        _osc_freq_str = f" at {_osc_freq}Hz" if _osc_freq else ""
        crystal_circuits.append({
            "reference": ref,
            "value": comp.get("value", ""),
            "frequency": _osc_freq,
            "type": "active_oscillator",
            "output_net": out_net,
            "load_caps": [],
            "detector": "detect_crystal_circuits",
            "rule_id": "XL-DET",
            "category": "timing",
            "severity": "info",
            "confidence": "deterministic",
            "evidence_source": "topology",
            "summary": f"Crystal {ref}{_osc_freq_str}",
            "description": "Active oscillator detected",
            "components": [ref],
            "nets": [],
            "pins": [],
            "recommendation": "",
            "report_context": {"section": "Timing", "impact": "", "standard_ref": ""},
            "provenance": make_provenance("xtal_active_oscillator", "deterministic", [ref]),
        })

    # IC pin-based crystal detection: find ICs with crystal-related pin names
    # (XTAL_IN/XTAL_OUT, XI/XO, OSC_IN/OSC_OUT) whose connected nets have small
    # caps (5-50pF) to ground.  Reports crystal circuits even without a classified
    # crystal component (common when crystal is in a generic footprint).
    _xtal_pin_re = re.compile(
        r'^(XTAL|OSC|XI|XO|XTAL_IN|XTAL_OUT|XTAL1|XTAL2|'
        r'OSC_IN|OSC_OUT|OSC1|OSC2|OSC32_IN|OSC32_OUT|'
        r'OSCI|OSCO|X_IN|X_OUT|XIN|XOUT|XT1|XT2|'
        r'XTALIN|XTALOUT|XTAL_P|XTAL_N|'
        r'RTC_XTAL|RTC_XI|RTC_XO|RTC32K_XP|RTC32K_XN)$', re.IGNORECASE)
    detected_refs = {xc["reference"] for xc in crystal_circuits}
    for ic in ctx.components:
        if ic["type"] != "ic":
            continue
        # Collect crystal-related pin nets for this IC
        xtal_pin_nets = []
        for pin in ic.get("pins", []):
            pname = pin.get("name", "")
            if _xtal_pin_re.match(pname):
                net_name, _ = ctx.pin_net.get((ic["reference"], pin["number"]), (None, None))
                if net_name and not ctx.is_power_net(net_name) and not ctx.is_ground(net_name):
                    xtal_pin_nets.append((pname, net_name))
        if len(xtal_pin_nets) < 2:
            continue
        # Check if these nets have small caps to ground (load caps)
        load_caps = []
        for _pname, net_name in xtal_pin_nets:
            if net_name not in ctx.nets:
                continue
            for p in ctx.nets[net_name]["pins"]:
                comp = ctx.comp_lookup.get(p["component"])
                if not comp or comp["type"] != "capacitor":
                    continue
                cap_ref = p["component"]
                if cap_ref in detected_refs or _dnp_cap_beside_fitted(ctx, cap_ref):
                    continue
                cap_val = ctx.parsed_values.get(cap_ref)
                if cap_val and 5e-12 <= cap_val <= 50e-12:
                    cn1, cn2 = ctx.get_two_pin_nets(cap_ref)
                    other = cn2 if cn1 == net_name else cn1
                    if ctx.is_ground(other):
                        load_caps.append({
                            "ref": cap_ref,
                            "value": comp["value"],
                            "farads": cap_val,
                            "net": net_name,
                        })
        if len(load_caps) >= 2:
            # Check if any crystal component already covers these nets
            cap_nets = {lc["net"] for lc in load_caps}
            already_covered = False
            for xc in crystal_circuits:
                if any(lc["net"] in cap_nets for lc in xc.get("load_caps", [])):
                    already_covered = True
                    break
            if not already_covered:
                # Look for a feedback resistor bridging the two crystal nets
                fb_resistor = None
                net_list = list(cap_nets)
                if len(net_list) >= 2:
                    for r in ctx.components:
                        if r["type"] != "resistor":
                            continue
                        rn1, rn2 = ctx.get_two_pin_nets(r["reference"])
                        if rn1 in cap_nets and rn2 in cap_nets and rn1 != rn2:
                            rv = ctx.parsed_values.get(r["reference"])
                            if rv and rv >= 100e3:  # 100k+ = feedback resistor
                                fb_resistor = r["reference"]
                                break

                entry = {
                    "reference": ic["reference"],
                    "value": ic.get("value", ""),
                    "type": "ic_crystal_pins",
                    "ic_reference": ic["reference"],
                    "load_caps": load_caps,
                }
                if fb_resistor:
                    entry["feedback_resistor"] = fb_resistor
                legs = _load_legs(load_caps)
                if len(legs) >= 2:
                    c1, c2 = legs[0], legs[1]
                    cl_eff = (c1 * c2) / (c1 + c2) + 3e-12
                    entry["effective_load_pF"] = round(cl_eff * 1e12, 2)
                entry["detector"] = "detect_crystal_circuits"
                entry["rule_id"] = "XL-DET"
                entry["category"] = "timing"
                entry["severity"] = "info"
                entry["confidence"] = "deterministic"
                entry["evidence_source"] = "topology"
                entry["summary"] = f"Crystal {ic['reference']}"
                entry["description"] = "Crystal circuit inferred from IC XTAL pins"
                entry["components"] = [ic["reference"]]
                entry["nets"] = []
                entry["pins"] = []
                entry["recommendation"] = ""
                entry["report_context"] = {"section": "Timing", "impact": "", "standard_ref": ""}
                entry["provenance"] = make_provenance(
                    "xtal_ic_pin_inferred", "heuristic",
                    [ic["reference"]] + [lc["ref"] for lc in load_caps])
                crystal_circuits.append(entry)

    return crystal_circuits


def detect_decoupling(ctx: AnalysisContext) -> list[dict]:
    """Detect decoupling capacitors per power rail."""
    # EQ-069: f_SRF = 1/(2π√(ESL×C)) (decoupling SRF)
    decoupling_analysis: list[dict] = []

    # For each power rail, compute total decoupling capacitance and frequency coverage
    power_nets = {}
    for net_name, net_info in ctx.nets.items():
        if net_name.startswith("__unnamed_"):
            continue
        if ctx.is_ground(net_name):
            continue
        if ctx.is_power_net(net_name):
            power_nets[net_name] = net_info

    for rail_name, rail_info in power_nets.items():
        rail_caps = []
        for p in rail_info["pins"]:
            comp = ctx.comp_lookup.get(p["component"])
            if comp and comp["type"] == "capacitor":
                cap_val = ctx.parsed_values.get(p["component"])
                if cap_val:
                    # Check if other pin goes to ground
                    c_n1, c_n2 = ctx.get_two_pin_nets(p["component"])
                    other = c_n2 if c_n1 == rail_name else c_n1
                    if ctx.is_ground(other):
                        self_resonant = 1.0 / (2.0 * math.pi * math.sqrt(1e-9 * cap_val))  # ~1nH ESL estimate
                        rail_caps.append({
                            "ref": p["component"],
                            "value": comp["value"],
                            "farads": cap_val,
                            "self_resonant_hz": round(self_resonant, 0),
                        })

        if rail_caps:
            total_cap = sum(c["farads"] for c in rail_caps)
            decoupling_analysis.append({
                "rail": rail_name,
                "capacitors": rail_caps,
                "total_capacitance_uF": round(total_cap * 1e6, 3),
                "cap_count": len(rail_caps),
                "detector": "detect_decoupling",
                "rule_id": "DC-DET",
                "category": "decoupling",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Decoupling on {rail_name}",
                "description": f"Decoupling capacitors on power rail {rail_name}",
                "components": [c["ref"] for c in rail_caps],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Decoupling", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("decoup_cap_near_ic", "deterministic", [c["ref"] for c in rail_caps]),
            })
    return decoupling_analysis


# Input pins of current-sense amplifiers (INA219 IN+/IN-, INA180 VIN+/VIN-, MAX4080 RS+/RS-).
# Op-amps share these names, so they count only on a known sense IC.
_SENSE_AMP_INPUT_PINS = frozenset({"IN+", "IN-", "VIN+", "VIN-", "RS+", "RS-"})


def _sense_ics_across(ctx: AnalysisContext, net_a: str, net_b: str,
                      keywords: frozenset, exclude: frozenset) -> set[str]:
    """Known sense-amplifier ICs with a pin on both nets."""
    def ics_on(net):
        return {p["component"] for p in ctx.nets.get(net, {}).get("pins", [])}
    found = set()
    for ref in ics_on(net_a) & ics_on(net_b):
        comp = ctx.comp_lookup.get(ref)
        if not comp or comp["type"] != "ic":
            continue
        val = (comp.get("value", "") + " " + comp.get("lib_id", "")).lower()
        if any(kw in val for kw in keywords) and not any(kw in val for kw in exclude):
            found.add(ref)
    return found


def _sense_pin_key(pin_name: str) -> str:
    return pin_name.upper().rstrip("0123456789").rstrip("_")


def _opposite_input_reaches(ctx: AnalysisContext, ref: str, pin_key: str,
                            net: str, shunt_refs: list) -> bool:
    """True when ``ref``'s opposite input (IN+ for IN-) is on ``net``, directly or
    through one resistor (an input filter), so the shunt sits between its inputs."""
    want = pin_key[:-1] + ("-" if pin_key.endswith("+") else "+")
    reach = {net}
    for p in ctx.nets.get(net, {}).get("pins", []):
        r_comp = ctx.comp_lookup.get(p["component"])
        if r_comp and r_comp["type"] == "resistor" and p["component"] not in shunt_refs:
            a, b = ctx.get_two_pin_nets(p["component"])
            if a and b:
                reach.add(b if a == net else a)
    return any(p["component"] == ref and _sense_pin_key(p.get("pin_name", "")) == want
               for n in reach for p in ctx.nets.get(n, {}).get("pins", []))


def detect_current_sense(ctx: AnalysisContext) -> list[dict]:
    """Detect current sense circuits."""
    current_sense: list[dict] = []
    # Parallel shunts are one equivalent shunt
    shunt_candidates = [
        c for c in group_reps(ctx, get_components_by_type(ctx, "resistor", with_parsed_values=True))
        if 0 < group_value(ctx, c["reference"]) <= 0.5
    ]

    _SENSE_PIN_PREFIXES = frozenset({
        "CS", "CSP", "CSN", "ISNS", "ISENSE", "IMON", "IOUT",
        "SEN", "SENSE", "VSENSE", "VSEN", "VS", "INP", "INN",
        "IS", "IAVG", "ISET",
    })
    _SENSE_IC_KEYWORDS = frozenset({
        "ina", "acs7", "ad8210", "ad8217", "ad8218", "max9938",
        "max4080", "max4081", "max471", "ltc6101", "ltc6102",
        "ltc6103", "ltc4151", "ina226", "ina233", "ina180",
        "ina181", "ina190", "ina199", "ina200", "ina210",
        "ina240", "ina250", "ina260", "ina300", "ina381",
        "pam2401", "zxct", "acs71", "acs72", "asc",
    })
    # IC families that are never current sense amplifiers
    _SENSE_IC_EXCLUDE = frozenset({
        # Ethernet PHY / RJ45 / MagJack
        "w5500", "w5100", "w5200", "ksz", "dp83", "lan87", "lan91",
        "hr911", "rj45", "magjack", "enc28j", "8p8c", "hr601", "arjm",
        # RS-485/RS-232/UART transceivers
        "lt178", "max48", "sn65hvd", "st348", "rs485", "rs232",
        "adm281", "adm485", "adm491", "sp338", "sp339", "isl3", "iso15",
        "max23", "max31", "max32",
    })

    for shunt in shunt_candidates:
        shunt_refs = group_members(ctx, shunt["reference"])
        # Support both 2-pin and 4-pin Kelvin shunts (R_Shunt: pins 1,4=current; 2,3=sense)
        sense_n1, sense_n2 = None, None
        # Check for 4-pin Kelvin first (pins 1,4=current path; 2,3=sense)
        n1, _ = ctx.pin_net.get((shunt["reference"], "1"), (None, None))
        n4, _ = ctx.pin_net.get((shunt["reference"], "4"), (None, None))
        n3, _ = ctx.pin_net.get((shunt["reference"], "3"), (None, None))
        if n1 and n4 and n3:
            # 4-pin Kelvin shunt
            n2, _ = ctx.pin_net.get((shunt["reference"], "2"), (None, None))
            s_n1, s_n2 = n1, n4
            sense_n1, sense_n2 = n2, n3
        else:
            s_n1, s_n2 = ctx.get_two_pin_nets(shunt["reference"])
            if not s_n1 or not s_n2:
                continue
        if s_n1 == s_n2:
            continue
        # Skip if both nets are power/ground (bulk decoupling, not sensing). A rail known
        # only by its pins is a sense side here: a shunt feeding one is still a shunt.
        s1_pwr_or_gnd = ctx.is_ground(s_n1) or ctx.is_power_net(s_n1, by_pins=False)
        s2_pwr_or_gnd = ctx.is_ground(s_n2) or ctx.is_power_net(s_n2, by_pins=False)
        if s1_pwr_or_gnd and s2_pwr_or_gnd:
            # Between two rails (VBAT -> VBAT_LOAD) it is a shunt only when a known
            # sense amplifier has pins on both of them.
            if ctx.is_ground(s_n1) or ctx.is_ground(s_n2):
                continue
            rail_sense_ics = _sense_ics_across(ctx, s_n1, s_n2, _SENSE_IC_KEYWORDS, _SENSE_IC_EXCLUDE)
            if not rail_sense_ics:
                continue

        shunt_ohms = group_value(ctx, shunt["reference"])

        # Find ICs connected to BOTH sides of the shunt.
        # Ground-net exclusion: GND connects to every IC on the board, so it
        # can't be used for "IC on both sides" matching.  When one side of the
        # shunt is GND, skip GND-side component collection entirely and instead
        # match only ICs on the non-GND side that are known sense parts or have
        # sense-related pin names on the shunt nets.

        # Treat power nets the same as GND — they connect to many ICs
        # through power pins and would cause the same false positive flood.
        side1_is_pwr = ctx.is_ground(s_n1) or ctx.is_power_net(s_n1, by_pins=False)
        side2_is_pwr = ctx.is_ground(s_n2) or ctx.is_power_net(s_n2, by_pins=False)
        has_pwr_side = side1_is_pwr or side2_is_pwr

        comps_on_n1 = set()
        comps_on_n2 = set()
        check_nets_1 = [s_n1] + ([sense_n1] if sense_n1 else [])
        check_nets_2 = [s_n2] + ([sense_n2] if sense_n2 else [])

        # Collect components on each side (skip power/GND side entirely)
        if not side1_is_pwr:
            for nn in check_nets_1:
                if nn in ctx.nets:
                    for p in ctx.nets[nn]["pins"]:
                        if p["component"] not in shunt_refs:
                            comps_on_n1.add(p["component"])
        if not side2_is_pwr:
            for nn in check_nets_2:
                if nn in ctx.nets:
                    for p in ctx.nets[nn]["pins"]:
                        if p["component"] not in shunt_refs:
                            comps_on_n2.add(p["component"])

        if s1_pwr_or_gnd and s2_pwr_or_gnd:
            sense_ics = rail_sense_ics
        elif has_pwr_side:
            # One side is a power/GND rail: use only the non-power side's
            # components.  Filter to ICs that are plausible current sense
            # monitors: either by part name or by having sense-related pin
            # names on the shunt nets.
            non_pwr_comps = comps_on_n1 if not side1_is_pwr else comps_on_n2
            non_pwr_nets = check_nets_1 if not side1_is_pwr else check_nets_2
            sense_ics_set = set()
            for cref in non_pwr_comps:
                ic_comp = ctx.comp_lookup.get(cref)
                if not ic_comp or ic_comp["type"] != "ic":
                    continue
                # Check if part is a known sense IC
                val_lower = (ic_comp.get("value", "") + " " + ic_comp.get("lib_id", "")).lower()
                # Skip excluded IC families
                if any(kw in val_lower for kw in _SENSE_IC_EXCLUDE):
                    continue
                if any(kw in val_lower for kw in _SENSE_IC_KEYWORDS):
                    sense_ics_set.add(cref)
                    continue
                # Check if the IC's pin on this net has a sense-related name
                for nn in non_pwr_nets:
                    if nn not in ctx.nets:
                        continue
                    for p in ctx.nets[nn]["pins"]:
                        if p["component"] == cref:
                            pn = p.get("pin_name", "").upper().rstrip("0123456789+-")
                            if pn in _SENSE_PIN_PREFIXES:
                                sense_ics_set.add(cref)
            sense_ics = sense_ics_set
        else:
            # Neither side is GND: use original "IC on both sides" algorithm
            sense_ics = comps_on_n1 & comps_on_n2
            # 1-hop: if no IC on both sides directly, look through filter resistors
            # (e.g., shunt -> R_filter -> sense IC is a common BMS pattern)
            if not any(ctx.comp_lookup.get(c, {}).get("type") == "ic" for c in sense_ics):
                for nn in check_nets_1:
                    if nn not in ctx.nets:
                        continue
                    for p in ctx.nets[nn]["pins"]:
                        r_comp = ctx.comp_lookup.get(p["component"])
                        if r_comp and r_comp["type"] == "resistor" and p["component"] not in shunt_refs:
                            r_other = ctx.get_two_pin_nets(p["component"])
                            if r_other[0] and r_other[1]:
                                hop_net = r_other[1] if r_other[0] == nn else r_other[0]
                                if hop_net in ctx.nets:
                                    for hp in ctx.nets[hop_net]["pins"]:
                                        comps_on_n1.add(hp["component"])
                for nn in check_nets_2:
                    if nn not in ctx.nets:
                        continue
                    for p in ctx.nets[nn]["pins"]:
                        r_comp = ctx.comp_lookup.get(p["component"])
                        if r_comp and r_comp["type"] == "resistor" and p["component"] not in shunt_refs:
                            r_other = ctx.get_two_pin_nets(p["component"])
                            if r_other[0] and r_other[1]:
                                hop_net = r_other[1] if r_other[0] == nn else r_other[0]
                                if hop_net in ctx.nets:
                                    for hp in ctx.nets[hop_net]["pins"]:
                                        comps_on_n2.add(hp["component"])
                sense_ics = comps_on_n1 & comps_on_n2
        for ic_ref in sorted(sense_ics):
            ic_comp = ctx.comp_lookup.get(ic_ref)
            if not ic_comp:
                continue
            # Only consider ICs (sense amplifiers, MCUs with ADC)
            if ic_comp["type"] not in ("ic",):
                continue

            current_sense.append({
                "shunt": group_part(ctx, shunt["reference"], "ohms"),
                "sense_ic": {
                    "ref": ic_ref,
                    "value": ic_comp.get("value", ""),
                    "type": ic_comp.get("type", ""),
                },
                "high_net": s_n1,
                "low_net": s_n2,
                "max_current_50mV_A": round(0.05 / shunt_ohms, 3) if shunt_ohms > 0 else None,
                "max_current_100mV_A": round(0.1 / shunt_ohms, 3) if shunt_ohms > 0 else None,
                "detector": "detect_current_sense",
                "rule_id": "CS-DET",
                "category": "current_measurement",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Current sense {shunt['reference']}",
                "description": "Current sense shunt with amplifier IC detected",
                "provenance": make_provenance("cs_ic_differential", "deterministic", [shunt["reference"], ic_ref]),
                "components": shunt_refs + [ic_ref],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Current Measurement", "impact": "", "standard_ref": ""},
            })
    # Second pass: detect shunts with IC-integrated current sense amplifiers.
    # These ICs have sense pins (CSA, SEN, SNS, ISENSE, IMON, CSP, CSN, SH)
    # but weren't caught by the first pass because they may not be on both sides.
    matched_shunts = {entry["shunt"]["ref"] for entry in current_sense}
    _integrated_csa_pins = frozenset({
        "CSA", "CSB", "SEN", "SENP", "SENN", "SNS", "SNSP", "SNSN",
        "ISENSE", "IMON", "IOUT", "CSP", "CSN", "CS+", "CS-",
        "SH", "SHP", "SHN", "ISENP", "ISENN",
    })

    for shunt in shunt_candidates:
        if shunt["reference"] in matched_shunts:
            continue
        shunt_ohms = group_value(ctx, shunt["reference"])
        if not shunt_ohms or shunt_ohms > 1.0:
            continue

        s_n1, s_n2 = ctx.get_two_pin_nets(shunt["reference"])
        if not s_n1 or not s_n2 or s_n1 == s_n2:
            continue

        # Check each side's net for IC pins with CSA-related names
        for net_name in (s_n1, s_n2):
            if net_name not in ctx.nets:
                continue
            for p in ctx.nets[net_name]["pins"]:
                ic_comp = ctx.comp_lookup.get(p["component"])
                if not ic_comp or ic_comp["type"] != "ic":
                    continue
                # Skip excluded IC families
                _val_lower2 = (ic_comp.get("value", "") + " " + ic_comp.get("lib_id", "")).lower()
                if any(kw in _val_lower2 for kw in _SENSE_IC_EXCLUDE):
                    continue
                pn = _sense_pin_key(p.get("pin_name", ""))
                if pn in _integrated_csa_pins or (
                        pn in _SENSE_AMP_INPUT_PINS
                        and any(kw in _val_lower2 for kw in _SENSE_IC_KEYWORDS)
                        and _opposite_input_reaches(
                            ctx, p["component"], pn, s_n2 if net_name == s_n1 else s_n1,
                            group_members(ctx, shunt["reference"]))):
                    current_sense.append({
                        "shunt": group_part(ctx, shunt["reference"], "ohms"),
                        "sense_ic": {
                            "ref": p["component"],
                            "value": ic_comp.get("value", ""),
                            "type": "integrated_csa",
                        },
                        "high_net": s_n1,
                        "low_net": s_n2,
                        "max_current_50mV_A": round(0.05 / shunt_ohms, 3) if shunt_ohms > 0 else None,
                        "max_current_100mV_A": round(0.1 / shunt_ohms, 3) if shunt_ohms > 0 else None,
                        "detector": "detect_current_sense",
                        "rule_id": "CS-DET",
                        "category": "current_measurement",
                        "severity": "info",
                        "confidence": "deterministic",
                        "evidence_source": "topology",
                        "summary": f"Current sense {shunt['reference']}",
                        "description": "Current sense shunt with integrated CSA detected",
                        "components": group_members(ctx, shunt["reference"]) + [p["component"]],
                        "nets": [],
                        "pins": [],
                        "recommendation": "",
                        "report_context": {"section": "Current Measurement", "impact": "", "standard_ref": ""},
                        "provenance": make_provenance("cs_integrated_pin", "heuristic", [shunt["reference"], p["component"]]),
                    })
                    matched_shunts.add(shunt["reference"])
                    break
            if shunt["reference"] in matched_shunts:
                break

    return current_sense


def _infer_rail_voltage(net_name):
    """Infer voltage from a power rail net name. Returns float or None."""
    if not net_name:
        return None
    name = net_leaf(net_name).upper().strip()
    # A leading minus is a negative rail (-5V, -VBAT)
    if name.startswith("-"):
        v = _infer_rail_voltage(name[1:])
        return -v if v else v
    # VxPy notation: V3P3 → 3.3, V1P8 → 1.8
    m = re.match(r'V(\d+)P(\d+)', name)
    if m:
        return float(f"{m.group(1)}.{m.group(2)}")
    m = re.match(r'[+]?(\d+)V(\d+)', name)
    if m:
        return float(f"{m.group(1)}.{m.group(2)}")
    m = re.match(r'[+]?(\d+\.?\d*)V', name)
    if m:
        return float(m.group(1))
    if "VBUS" in name:
        return 5.0
    # only non-data USB nets (VBUS-ish) default to 5V
    if "USB" in name and not is_usb_data_net_name(name):
        return 5.0
    if "VBAT" in name:
        return 3.7
    return None


@dataclass
class _RegulatorCandidate:
    """An IC that passed the regulator screen, with the pin roles and name keys the build phase reads."""
    ic: dict
    ref: str
    ic_pins: dict
    fb_pin: tuple | None
    sw_pin: tuple | None
    vin_pin: tuple | None
    vout_pin: tuple | None
    boot_pin: tuple | None
    lib_part_name: str
    desc_lower: str
    lib_val_lower: str
    has_reg_keyword: bool
    fb_candidates: tuple = ()  # every FB/ADJ pin as (name, net), in natural name order


def detect_power_regulators(ctx: AnalysisContext, voltage_dividers: list[dict]) -> list[dict]:
    """Detect power regulator topology. Takes voltage_dividers for feedback matching."""
    power_regulators: list[dict] = []

    # Deduplicate multi-unit ICs
    for ic in get_unique_ics(ctx):
        cand = _screen_regulator_candidate(ctx, ic)
        if cand is None:
            continue
        if isinstance(cand, dict):
            power_regulators.append(cand)
            continue
        power_regulators.append(_build_regulator_record(ctx, cand, voltage_dividers))

    _cross_reference_feedback_dividers(power_regulators, voltage_dividers)
    _attach_regulator_capacitors(ctx, power_regulators)
    _estimate_regulator_dissipation(ctx, power_regulators)

    return power_regulators


# A GPIO on a port other than H (PA0, PB12). On a part with such pins, PH0/PH1 are port H GPIOs,
# not switch pins. H is left out because a multi-phase regulator's PH1/PH2 would match it.
_GPIO_PORT_PIN = re.compile(r"^P[A-GI-K]\d{1,2}$")


def _screen_regulator_candidate(ctx: AnalysisContext, ic: dict) -> _RegulatorCandidate | dict | None:
    """Reject non-regulators; return the keyword-only PMIC record finished, else the candidate."""
    ref = ic["reference"]

    # Skip components with no mapped pins (title blocks, graphics)
    # Allow keyword-matched PMICs through even without pins (legacy format)
    _no_pins = not ic.get("pins")

    # Skip known non-regulator IC families
    _lib_val_check = (ic.get("lib_id", "") + " " + ic.get("value", "")).lower()
    _non_reg_exclude = ("eeprom", "flash", "spi_flash", "rtc", "uart",
                        "usb_uart", "buffer", "logic_", "encoder",
                        "w25q", "at24c", "24c0", "pcf85", "ht42b", "ch340",
                        "cp210", "ft232", "74lvc", "74hc",
                        # WiFi/BT modules with filter inductors
                        "ap6212", "ap6236", "ap6256", "esp32", "esp8266",
                        "cyw43", "wl18",
                        # Dev board modules (not regulators)
                        "nucleo", "arduino", "raspberry", "teensy",
                        "feather", "pico")
    if any(k in _lib_val_check for k in _non_reg_exclude):
        return None

    ic_pins = {}  # pin_name -> (net_name, pin_number)
    for pin_num, (net_name, _) in ctx.ref_pins.get(ref, {}).items():
        pin_name = ""
        if net_name and net_name in ctx.nets:
            for p in ctx.nets[net_name]["pins"]:
                if p["component"] == ref and p["pin_number"] == pin_num:
                    pin_name = p.get("pin_name", "").upper()
                    break
        ic_pins[pin_name] = (net_name, pin_num)

    # Look for regulator pin patterns
    fb_pin = None
    sw_pin = None
    en_pin = None
    vin_pin = None
    vout_pin = None
    boot_pin = None
    fb_candidates = []

    has_gpio_ports = any(_GPIO_PORT_PIN.match(n) for n in ic_pins)
    for pname, (net, pnum) in ic_pins.items():
        # Use startswith for pins that may have numeric suffixes (FB1, SW2, etc.)
        pn_base = pname.rstrip("0123456789").rstrip("_")  # Strip trailing digits and underscores (FB_1→FB)
        if pn_base == "PH" and pname != "PH" and has_gpio_ports:
            pn_base = pname
        # Split composite pin names like "FB/VOUT" into parts
        pn_parts = {p.strip() for p in pname.split("/")} | {pn_base}
        if pn_parts & {"FB", "VFB", "ADJ", "VADJ"}:
            fb_candidates.append((pname, net))
            # Composite names like "FB/VOUT" also set vout_pin
            if not vout_pin and pn_parts & _VOUT_PIN_NAMES:
                vout_pin = (pname, net)
        elif pn_parts & {"SW", "PH", "LX"}:
            if not sw_pin:
                sw_pin = (pname, net)
        elif pname in ("EN", "ENABLE", "ON", "~{SHDN}", "SHDN", "~{EN}") or \
             (pn_base == "EN" and len(pname) <= 4):
            en_pin = (pname, net)
        elif pn_parts & {"VIN", "VI", "IN", "PVIN", "AVIN", "INPUT"}:
            vin_pin = (pname, net)
        elif pn_parts & _VOUT_PIN_NAMES:
            vout_pin = (pname, net)
        elif pn_parts & _BOOTSTRAP_PIN_TOKENS:
            boot_pin = (pname, net)

    # Order several FB pins by name (ADJ1 before ADJ2), not by net enumeration order
    fb_candidates.sort(key=lambda c: [int(t) if t.isdigit() else t for t in re.split(r"(\d+)", c[0])])
    if fb_candidates:
        fb_pin = fb_candidates[0]

    if not fb_pin and not sw_pin and not vout_pin:
        # For pin-less ICs (legacy format), check keywords before
        # giving up — PMICs like AXP803 won't have pin data
        if not _no_pins:
            return None  # Not a regulator
        _kw_check = (ic.get("lib_id", "") + " " + ic.get("value", "")).lower()
        _kw_pmic = ("regulator", "ldo", "buck", "boost", "converter", "pmic",
                    "axp", "mt36", "dd40", "tplp", "hx630", "ip51",
                    "ams1117", "lm317", "lm78", "lm79", "tps5", "tps6")
        if not any(k in _kw_check for k in _kw_pmic):
            return None
        # Add as minimal keyword-only entry
        return {
            "ref": ref,
            "value": ic.get("value", ""),
            "lib_id": ic.get("lib_id", ""),
            "topology": "unknown",
            "input_rail": None,
            "output_rail": None,
            "estimated_vout": None,
            "feedback_divider": None,
            "inductor": None,
            "detector": "detect_power_regulators",
            "rule_id": "PR-DET",
            "category": "power_management",
            "severity": "info",
            "confidence": "deterministic",
            "evidence_source": "topology",
            "summary": f"Regulator {ref} unknown",
            "description": "Power regulator detected by keyword match (no pin data)",
            "components": [ref],
            "nets": [],
            "pins": [],
            "recommendation": "",
            "report_context": {"section": "Power Management", "impact": "", "standard_ref": ""},
            "provenance": make_provenance("reg_keyword", "heuristic", [ref]),
        }

    # Early lib_id check
    lib_id_raw = ic.get("lib_id", "")
    lib_part_name = lib_id_raw.split(":")[-1] if ":" in lib_id_raw else ""
    desc_lower = ic.get("description", "").lower()
    lib_val_lower = (lib_id_raw + " " + ic.get("value", "") + " " + lib_part_name).lower()
    reg_lib_keywords = ("regulator", "regul", "ldo", "vreg", "buck", "boost",
                       "converter", "dc-dc", "dc_dc", "linear_regulator",
                       "switching_regulator",
                       "ams1117", "lm317", "lm78", "lm79", "ld1117", "ld33",
                       "ap6", "tps5", "tps6", "tlv7", "rt5", "mp1", "mp2",
                       "sy8", "max150", "max170", "ncp1", "xc6", "mcp170",
                       "mic29", "mic55", "ap2112", "ap2210", "ap73",
                       "ncv4", "lm26", "lm11", "78xx",
                       "79xx", "lt308", "lt36", "ltc36", "lt86", "ltc34",
                       # Asian manufacturer LDOs
                       "tplp", "hx630",
                       # PMICs and boost converters
                       "axp", "mt36", "pmic", "dd40", "ip51",
                       )
    has_reg_keyword = (any(k in lib_val_lower for k in reg_lib_keywords) or
                      any(k in desc_lower for k in ("regulator", "ldo", "vreg",
                                                    "voltage regulator")))

    # Exclude RF amplifiers/LNAs that have VIN/VOUT but aren't regulators
    _rf_exclude = ("lna", "mmic", "mga-", "bga-", "bgb7", "trf37",
                   "sga-", "tqp3", "sky67", "gali-", "bfp7", "bfr5")
    if any(k in lib_val_lower for k in _rf_exclude):
        return None

    # Exclude power multiplexers/load switches/ideal diode controllers
    _power_mux_exclude = ("power_mux", "load_switch", "tps211", "tps212",
                          "tps205",  # load switches (more in LOAD_SWITCH_KEYWORDS)
                          "ltc441", "ideal_diode",
                          # Ideal diode OR controllers
                          "lm6620", "lm6610", "ltc435", "ltc430")
    if any(k in lib_val_lower for k in _power_mux_exclude + LOAD_SWITCH_KEYWORDS):
        return None
    # Exclude components with load/power switch descriptions
    if names_load_switch(desc_lower):
        return None

    # Exclude op-amps, instrumentation amps, and ADCs with FB-like pins
    _opamp_adc_exclude = ("ada48", "ad8", "opa", "lm358", "lm324",
                          "lmv3", "tlv9", "mcp60", "mcp61",
                          "hx711", "ads1", "mcp3", "max11",
                          "ina21", "ina22", "ina23",
                          "comparator", "op_amp", "opamp")
    if any(k in lib_val_lower for k in _opamp_adc_exclude):
        return None

    if not fb_pin and not boot_pin:
        if not sw_pin and not has_reg_keyword:
            # Only VOUT pin, no regulator keywords → check if VIN+VOUT
            # both connect to distinct power nets (custom-lib LDOs like TC1185)
            if vin_pin and vout_pin:
                in_net = vin_pin[1]
                out_net = vout_pin[1]
                if not (ctx.is_power_net(in_net) and ctx.is_power_net(out_net)
                        and in_net != out_net):
                    return None
            else:
                return None
        if sw_pin and not has_reg_keyword:
            # SW pin but check if inductor is connected
            sw_net_name = sw_pin[1]
            sw_has_inductor = bool(ctx.nq and ctx.nq.inductors_on_net(sw_net_name, exclude_ref=ref))
            if not sw_has_inductor and ctx.nq:
                # Try 1-hop through connectors/hierarchical pins
                for other_net in ctx.nq.trace_through(sw_net_name, ref):
                    if ctx.nq.inductors_on_net(other_net):
                        sw_has_inductor = True
                        break
            if not sw_has_inductor:
                return None

    return _RegulatorCandidate(
        ic=ic, ref=ref, ic_pins=ic_pins, fb_pin=fb_pin, sw_pin=sw_pin, vin_pin=vin_pin,
        vout_pin=vout_pin, boot_pin=boot_pin, lib_part_name=lib_part_name,
        desc_lower=desc_lower, lib_val_lower=lib_val_lower, has_reg_keyword=has_reg_keyword,
        fb_candidates=tuple(fb_candidates),
    )


# Common feedback reference voltages, tried in order when the part is not known.
_HEURISTIC_VREFS = (0.6, 0.8, 1.0, 1.22, 1.25)


def _heuristic_vref(ratio: float, rail: str | None) -> tuple[float | None, str]:
    """Vref and provenance source for an unknown part's divider *ratio*.

    The reference whose output lands closest to the voltage in the output rail's
    own name, within 10 %, else the first that gives a 0.5-60 V output.
    """
    rail_v = _parse_voltage_from_net_name(rail) if rail else None
    if rail_v:
        fits = [v for v in _HEURISTIC_VREFS
                if 0.5 < v / ratio < 60 and abs(v / ratio - abs(rail_v)) <= 0.1 * abs(rail_v)]
        if fits:
            return min(fits, key=lambda v: abs(v / ratio - abs(rail_v))), "divider_plus_rail_name"
    for v in _HEURISTIC_VREFS:
        if 0.5 < v / ratio < 60:
            return v, "divider_plus_heuristic"
    return None, ""


def _feedback_arm(arm: dict) -> dict:
    """A divider arm as a regulator's ``feedback_divider`` records it."""
    out = {"ref": arm["ref"], "ohms": arm["ohms"], "value": arm["value"]}
    if "parallel_refs" in arm:
        out["parallel_refs"] = arm["parallel_refs"]
    return out


def _is_potentiometer(ctx: AnalysisContext, ref: str) -> bool:
    """A potentiometer or trimmer: RV designator or a pot/trim symbol."""
    lib_id = (ctx.comp_lookup.get(ref) or {}).get("lib_id", "").lower()
    return ref.upper().startswith("RV") or "pot" in lib_id or "trim" in lib_id


def _part_nets(ctx: AnalysisContext, ref: str) -> list[str]:
    """The distinct nets on ``ref``'s pins, sorted."""
    return sorted({n for n, _ in ctx.ref_pins.get(ref, {}).values() if n})


def _is_three_net_pot(ctx: AnalysisContext, ref: str) -> bool:
    """A potentiometer on three distinct nets: not a two-terminal resistor.  One wired as a
    rheostat (two of its pins on one net) is a resistor between its two nets."""
    return _is_potentiometer(ctx, ref) and len(_part_nets(ctx, ref)) > 2


def _datasheet_vref(ctx: AnalysisContext, ic: dict) -> float | None:
    """Feedback reference voltage (V, typ) from a trusted datasheet extraction, or None.

    Trusted as in ``datasheet_features``: score at least 60 and the PDF unchanged;
    the value itself needs medium extractor confidence.
    """
    mpn = ic.get("mpn") or ic.get("value") or ""
    facts = get_facts(mpn, cache_dir=getattr(ctx, "cache_dir", None),
                      diagnostics=getattr(ctx, "diagnostics", None)) if mpn else None
    reg = getattr(facts, "regulator", None)
    if reg is None or not facts_trusted(facts):
        return None
    sv = best(reg.reference_voltage, min_confidence="medium") if has_data(reg.reference_voltage) else None
    if sv is None or sv.typ is None or sv.unit != "V":
        return None
    return sv.typ


def _build_regulator_record(ctx: AnalysisContext, cand: _RegulatorCandidate,
                            voltage_dividers: list[dict]) -> dict:
    """Topology, rails, Vout estimate, switching frequency and the PR-DET envelope for one candidate."""
    ref = cand.ref
    ic = cand.ic
    ic_pins = cand.ic_pins
    fb_pin = cand.fb_pin
    sw_pin = cand.sw_pin
    vin_pin = cand.vin_pin
    vout_pin = cand.vout_pin
    boot_pin = cand.boot_pin
    desc_lower = cand.desc_lower
    lib_val_lower = cand.lib_val_lower
    has_reg_keyword = cand.has_reg_keyword

    reg_info = {
        "ref": ref,
        "value": ic["value"],
        "lib_id": ic.get("lib_id", ""),
    }
    # Boost/inverting stages run the inductor from the input to SW; its far side is not the output.
    far_side_is_input = False

    # Determine topology
    if sw_pin:
        # Check if SW pin connects to an inductor
        sw_net = sw_pin[1]
        has_inductor = False
        inductor_ref = None
        inductors = ctx.nq.inductors_on_net(sw_net, exclude_ref=ref) if ctx.nq else []
        if not inductors and ctx.nq:
            # Try 1-hop through connectors for modular designs
            for other_net in ctx.nq.trace_through(sw_net, ref):
                inductors = ctx.nq.inductors_on_net(other_net)
                if inductors:
                    break
        if inductors:
            has_inductor = True
            inductor_ref = inductors[0]["reference"]
        if has_inductor:
            reg_info["topology"] = "switching"
            reg_info["inductor"] = inductor_ref
            reg_info["sw_net"] = sw_net
            if boot_pin:
                reg_info["has_bootstrap"] = True
            # Trace through inductor to find output rail
            if inductor_ref and not vout_pin:
                ind_n1, ind_n2 = ctx.get_two_pin_nets(inductor_ref)
                out_rail = ind_n2 if ind_n1 == sw_net else ind_n1
                if out_rail and vin_pin and out_rail == vin_pin[1]:
                    far_side_is_input = True
                elif out_rail and out_rail != sw_net:
                    reg_info["output_rail"] = out_rail
        else:
            reg_info["topology"] = "switching"  # SW pin but no inductor found
    elif vout_pin and not sw_pin:
        # Check if description/lib_id suggests a switching regulator whose
        # SW pin wasn't found (e.g., pin in different unit or unusual name)
        _switching_kw = ("buck", "boost", "switching", "step-down", "step-up",
                         "step down", "step up", "dc-dc", "dc_dc", "smps",
                         "converter", "synchronous")
        if any(k in desc_lower for k in _switching_kw) or \
           any(k in lib_val_lower for k in _switching_kw):
            reg_info["topology"] = "switching"
        elif _match_known_switching(ic.get("value", ""), ic.get("lib_id", "")):
            reg_info["topology"] = "switching"
        else:
            reg_info["topology"] = "LDO"
        # Charge pumps — voltage converters, not LDOs
        _charge_pump_kw = ("charge_pump", "charge pump", "voltage inverter",
                           "voltage converter", "switched capacitor")
        if any(k in desc_lower for k in _charge_pump_kw) or \
           any(k in lib_val_lower for k in ("lm2664", "max660", "icl7660",
                                              "tc7660", "ltc1044", "ltc3261",
                                              "ltc1144")):
            reg_info["topology"] = "charge_pump"
    elif fb_pin and not sw_pin:
        reg_info["topology"] = "unknown"

    # Check if this is a complex IC with an internal regulator rather than
    # a dedicated regulator.  If < 20% of pins are regulator-related, flag it.
    total_pins = len(ic.get("pins", []))
    reg_pin_count = sum(1 for pn in ic_pins if pn in (
        "VIN", "VOUT", "VO", "OUT", "FB", "VFB", "ADJ", "SW", "PH", "LX",
        "EN", "ENABLE", "BST", "BOOT", "PGOOD", "PG", "SS", "COMP",
        "INPUT", "OUTPUT",
    ))
    if total_pins > 10 and reg_pin_count < total_pins * 0.2:
        reg_info["topology"] = "ic_with_internal_regulator"

    # Detect inverting topology from part name/description or output net name
    inverting_kw = ("invert", "inv_", "_inv", "negative output", "neg_out")
    is_inverting = any(k in lib_val_lower for k in inverting_kw) or \
                   any(k in desc_lower for k in inverting_kw)

    # Extract input/output rails
    if vin_pin:
        reg_info["input_rail"] = vin_pin[1]
    if vout_pin:
        reg_info["output_rail"] = vout_pin[1]
        # Also check if the output rail's own name suggests a negative voltage (-5V, NEG12, V-,
        # the 4V5_N half of a 4V5_P / 4V5_N split supply); a sheet path is not part of it
        # (a UUID path holds "-<digit>")
        out_net_u = net_leaf(vout_pin[1]).upper()
        if re.search(r'[-](\d)', out_net_u) or "NEG" in out_net_u or out_net_u.startswith("-") \
                or out_net_u.endswith("-") or vout_pin[1] in negative_split_rails(ctx.nets):
            is_inverting = True
    if is_inverting:
        reg_info["inverting"] = True

    # Sanity check — power rails should never be GND
    if reg_info.get("input_rail") and ctx.is_ground(reg_info["input_rail"]):
        reg_info["input_rail"] = None
    if (reg_info.get("output_rail") and ctx.is_ground(reg_info["output_rail"])
            and reg_info["output_rail"] not in ctx.vss_supply_rails):
        reg_info["output_rail"] = None

    # Trace output rail through inductor (retry after sanitization)
    if reg_info.get("topology") == "switching" and not reg_info.get("output_rail") and reg_info.get("inductor"):
        ind_ref = reg_info["inductor"]
        ind_n1, ind_n2 = ctx.get_two_pin_nets(ind_ref)
        sw_net_2 = sw_pin[1] if sw_pin else None
        out_rail = ind_n2 if ind_n1 == sw_net_2 else ind_n1
        if out_rail and vin_pin and out_rail == vin_pin[1]:
            far_side_is_input = True
        elif out_rail and not ctx.is_ground(out_rail):
            reg_info["output_rail"] = out_rail

    # Trace input rail through ferrite bead
    if not reg_info.get("input_rail") and vin_pin:
        vin_net = vin_pin[1]
        if vin_net and vin_net in ctx.nets:
            for p in ctx.nets[vin_net]["pins"]:
                fb_comp = ctx.comp_lookup.get(p["component"])
                if (fb_comp and fb_comp["type"] in ("ferrite_bead", "inductor")
                        and p["component"] != reg_info.get("inductor")):
                    fb_n1, fb_n2 = ctx.get_two_pin_nets(p["component"])
                    other = fb_n2 if fb_n1 == vin_net else fb_n1
                    if other and ctx.is_power_net(other) and not ctx.is_ground(other):
                        reg_info["input_rail"] = other
                        break

    # Check for fixed-output regulator (voltage encoded in part number)
    fixed_vout, fixed_source = _lookup_regulator_vref(
        ic.get("value", ""), ic.get("lib_id", ""), ic.get("mpn") or "")
    if fixed_source == "fixed_suffix" and fixed_vout is not None:
        reg_info["estimated_vout"] = round(fixed_vout, 3)
        reg_info["vref_source"] = "fixed_suffix"
        reg_info["_estimated_vout_provenance"] = {
            "source": "fixed_suffix",
            "confidence": "deterministic",
        }
        if vout_pin and (not ctx.is_ground(vout_pin[1]) or vout_pin[1] in ctx.vss_supply_rails):
            reg_info["output_rail"] = vout_pin[1]

    # A multi-channel part has several FB pins: estimate the channel whose divider tops out on
    # the output rail; an FB pin tied straight to the output rail senses that channel (its divider,
    # if any, sits on another pin), so no other channel's divider applies; else the first with a
    # divider, else the first by name
    out_rail = reg_info.get("output_rail")
    fb_divided = [c for c in cand.fb_candidates
                  if any(vd["mid_net"] == c[1] and vd["ratio"] > 0 for vd in voltage_dividers)]
    fb_pin = next((c for c in fb_divided
                   if any(vd["mid_net"] == c[1] and vd["top_net"] == out_rail
                          for vd in voltage_dividers)),
                  None) or next((c for c in cand.fb_candidates if out_rail and c[1] == out_rail),
                                fb_divided[0] if fb_divided else fb_pin)

    # Check feedback divider for output voltage estimation
    if fb_pin:
        fb_net = fb_pin[1]
        reg_info["fb_net"] = fb_net
        # Vref from a trusted datasheet extraction, then the part-number table, then a heuristic sweep
        known_vref, vref_source = _lookup_regulator_vref(
            ic.get("value", ""), ic.get("lib_id", ""), ic.get("mpn") or "")
        # Skip feedback divider analysis for fixed-output parts
        if vref_source == "fixed_suffix":
            known_vref = None
        else:
            ds_vref = _datasheet_vref(ctx, ic)
            if ds_vref is not None:
                known_vref, vref_source = ds_vref, "datasheet"
        # A three-terminal adjustable (LM317 family) has no ground pin: its ADJ pin floats on the divider
        three_terminal = "ADJ" in {p.strip() for p in fb_pin[0].split("/")} and not any(
            net and ctx.is_ground(net) for pname, (net, _) in ic_pins.items() if pname != fb_pin[0])
        # Find matching voltage divider
        for vd in voltage_dividers:
            if vd["mid_net"] == fb_net:
                ratio = vd["ratio"]
                if ratio <= 0:
                    break
                vref_ratio = ratio
                if three_terminal:
                    # A trimmer's end stop is not the operating point
                    if any(_is_potentiometer(ctx, ref) for arm in ("r_top", "r_bottom")
                           for ref in vd[arm].get("parallel_refs") or [vd[arm]["ref"]]):
                        break
                    # LM317 datasheet: Vref sits across the OUT-ADJ (top) resistor, Vout = Vref x (1 + Rbot/Rtop)
                    vref_ratio = 1 - ratio
                    if vref_ratio <= 0:
                        break
                if known_vref is not None:
                    vref, prov_source = known_vref, "divider_plus_" + vref_source
                elif three_terminal:
                    # LM317/LM338/LM350/LT1085/LM1086/AZ1117-ADJ datasheets: 1.25 V across OUT-ADJ
                    vref, prov_source = 1.25, "divider_plus_heuristic"
                    vref_source = "heuristic"
                else:
                    vref, prov_source = _heuristic_vref(
                        vref_ratio, reg_info.get("output_rail") or vd.get("top_net"))
                    vref_source = "heuristic"
                if vref is not None and 0.5 < vref / vref_ratio < 60:
                    reg_info["estimated_vout"] = round(vref / vref_ratio, 3)
                    reg_info["_estimated_vout_provenance"] = {
                        "source": prov_source,
                        "confidence": "deterministic" if vref_source == "datasheet" else "heuristic",
                    }
                    reg_info["assumed_vref"] = vref
                    reg_info["vref_source"] = vref_source
                    reg_info["feedback_divider"] = {
                        "r_top": _feedback_arm(vd["r_top"]),
                        "r_bottom": _feedback_arm(vd["r_bottom"]),
                        "ratio": ratio,
                    }
                    if three_terminal:
                        reg_info["feedback_divider"]["reference"] = "out_adj"
                break

    # The boost output is the regulated rail at the top of the feedback divider
    if far_side_is_input and not reg_info.get("output_rail"):
        for vd in voltage_dividers:
            if fb_pin and vd["mid_net"] == fb_pin[1] and not ctx.is_ground(vd["top_net"]):
                reg_info["output_rail"] = vd["top_net"]
                # only a leading minus, V-, VEE or NEG: a boost's VCC-5V is positive
                top_leaf = net_leaf(vd["top_net"]).upper()
                if top_leaf.startswith(("-", "V-", "VEE")) or "NEG" in top_leaf:
                    reg_info["inverting"] = True
                break
        else:
            # read by _cross_reference_feedback_dividers, which removes it
            reg_info["_far_side_is_input"] = True

    # Fixed-output LDOs are never inverting
    if reg_info.get("inverting") and reg_info.get("topology") == "LDO" and not fb_pin:
        del reg_info["inverting"]

    # Negate Vout for inverting regulators
    if reg_info.get("inverting") and "estimated_vout" in reg_info:
        reg_info["estimated_vout"] = -abs(reg_info["estimated_vout"])

    # Estimate switching frequency for switching regulators
    if reg_info.get("topology") == "switching":
        sw_f = lookup_switching_freq(ic.get("value", ""))
        freq_source = "lookup_table" if sw_f else None
        if sw_f is None:
            # Try lib_id part name (after colon)
            lib_part = ic.get("lib_id", "").split(":")[-1] if ":" in ic.get("lib_id", "") else ""
            if lib_part:
                sw_f = lookup_switching_freq(lib_part)
                if sw_f:
                    freq_source = "lookup_table"
        if sw_f is None:
            sw_f = default_switching_freq("buck")  # conservative default for switching
            freq_source = "topology_default"
        if sw_f is not None:
            reg_info["switching_frequency_hz"] = sw_f
            reg_info["freq_source"] = freq_source

    # Only add if we found meaningful regulator features
    is_regulator = False
    if fb_pin or sw_pin or boot_pin:
        is_regulator = True
    elif vin_pin or vout_pin:
        in_net = vin_pin[1] if vin_pin else ""
        out_net = vout_pin[1] if vout_pin else ""
        if ctx.is_power_net(in_net) or ctx.is_power_net(out_net):
            is_regulator = True
        if has_reg_keyword:
            is_regulator = True

    if is_regulator and any(k in reg_info for k in ("topology", "input_rail", "output_rail", "estimated_vout")):
        _reg_topo = reg_info.get("topology", "unknown")
        reg_info["detector"] = "detect_power_regulators"
        reg_info["rule_id"] = "PR-DET"
        reg_info["category"] = "power_management"
        reg_info["severity"] = "info"
        reg_info["confidence"] = "deterministic"
        reg_info["evidence_source"] = "topology"
        reg_info["summary"] = f"Regulator {ref} {_reg_topo}"
        reg_info["description"] = f"Power regulator ({_reg_topo}) detected"
        reg_info["components"] = [ref]
        reg_info["nets"] = []
        reg_info["pins"] = []
        reg_info["recommendation"] = ""
        reg_info["report_context"] = {"section": "Power Management", "impact": "", "standard_ref": ""}
        # Determine provenance evidence based on classification path
        if sw_pin and reg_info.get("inductor"):
            _prov_evidence = "reg_sw_pin_inductor"
            _prov_confidence = "deterministic"
        elif reg_info.get("vref_source") == "fixed_suffix":
            _prov_evidence = "reg_fixed_suffix"
            _prov_confidence = "deterministic"
        elif sw_pin:
            _prov_evidence = "reg_sw_pin_only"
            _prov_confidence = "heuristic"
        elif reg_info.get("feedback_divider"):
            _prov_evidence = "reg_divider_vref"
            _prov_confidence = "heuristic"
        elif has_reg_keyword:
            _prov_evidence = "reg_keyword"
            _prov_confidence = "heuristic"
        else:
            _prov_evidence = "reg_keyword"
            _prov_confidence = "heuristic"
        reg_info["provenance"] = make_provenance(_prov_evidence, _prov_confidence, [ref])
        # every candidate passed the screen, so this guard holds and the None fall-through is never reached
        return reg_info


def _cross_reference_feedback_dividers(power_regulators: list[dict], voltage_dividers: list[dict]) -> None:
    """Give each regulator without a feedback divider the divider whose top net is its FB net (FB-at-top),
    and an output rail when it has none, in place."""
    # Cross-reference feedback dividers with regulators.
    # For dividers whose top_net matches a regulator's output_rail, mark as feedback.
    for reg in power_regulators:
        # an LED boost's FB-at-top node is its current sense, not an output rail
        far_side_is_input = reg.pop("_far_side_is_input", False)
        fb_net = reg.get("fb_net")
        if not fb_net or reg.get("feedback_divider"):
            continue
        # Check if FB net connects to divider top_net (FB-at-top topology)
        for vd in voltage_dividers:
            if vd["top_net"] == fb_net:
                ratio = vd["ratio"]
                # In FB-at-top, Vout = Vfb (the top of the divider IS the output)
                reg["feedback_divider"] = {
                    "r_top": _feedback_arm(vd["r_top"]),
                    "r_bottom": _feedback_arm(vd["r_bottom"]),
                    "ratio": ratio,
                    "topology": "fb_at_top",
                }
                if not reg.get("output_rail") and not far_side_is_input:
                    reg["output_rail"] = fb_net
                break


def _attach_regulator_capacitors(ctx: AnalysisContext, power_regulators: list[dict]) -> None:
    """Attach each regulator's output, input and FB-net compensation capacitors to its record, in place."""
    # Detect output capacitors on each regulator's output rail
    for reg in power_regulators:
        output_rail = reg.get("output_rail")
        reg_ref = reg.get("ref", "")
        if output_rail and output_rail in ctx.nets:
            output_caps = []
            seen_refs = set()
            for p in ctx.nets[output_rail]["pins"]:
                cref = p["component"]
                if cref == reg_ref or cref in seen_refs:
                    continue
                comp = ctx.comp_lookup.get(cref)
                if not comp or comp["type"] != "capacitor":
                    continue
                # the cap's other pin must be ground -- a
                # feedforward cap wired rail->FB (or similar) isn't a
                # decoupler and shouldn't be modeled as one.
                other = [n for n in ctx.get_two_pin_nets(cref) if n != output_rail]
                if not other or not ctx.is_ground(other[0]):
                    continue
                c_val = ctx.parsed_values.get(cref)
                if not c_val or c_val <= 0:
                    continue
                seen_refs.add(cref)
                cap_entry = {
                    "ref": cref,
                    "value": comp["value"],
                    "farads": c_val,
                }
                # Carry package from footprint for downstream rules (TH-001, PDN)
                fp = comp.get("footprint", "")
                if fp:
                    import re as _re
                    _pkg_m = _re.search(r'(\d{4})', fp)
                    if _pkg_m and _pkg_m.group(1) in (
                            '0201', '0402', '0603', '0805',
                            '1206', '1210', '1812', '2220'):
                        cap_entry["package"] = _pkg_m.group(1)
                output_caps.append(cap_entry)
            if output_caps:
                # Sort by value descending (bulk caps first)
                output_caps.sort(key=lambda c: -c["farads"])
                reg["output_capacitors"] = output_caps

        # Detect input capacitors on the input rail
        input_rail = reg.get("input_rail")
        if input_rail and input_rail in ctx.nets:
            input_caps = []
            seen_refs_in = set()
            for p in ctx.nets[input_rail]["pins"]:
                cref = p["component"]
                if cref == reg_ref or cref in seen_refs_in:
                    continue
                comp = ctx.comp_lookup.get(cref)
                if not comp or comp["type"] != "capacitor":
                    continue
                # same shunt-only guard as the output-cap collector.
                other = [n for n in ctx.get_two_pin_nets(cref) if n != input_rail]
                if not other or not ctx.is_ground(other[0]):
                    continue
                c_val = ctx.parsed_values.get(cref)
                if not c_val or c_val <= 0:
                    continue
                seen_refs_in.add(cref)
                cap_entry = {
                    "ref": cref,
                    "value": comp["value"],
                    "farads": c_val,
                }
                # Carry package from footprint for downstream rules (TH-001, PDN)
                fp = comp.get("footprint", "")
                if fp:
                    import re as _re
                    _pkg_m = _re.search(r'(\d{4})', fp)
                    if _pkg_m and _pkg_m.group(1) in (
                            '0201', '0402', '0603', '0805',
                            '1206', '1210', '1812', '2220'):
                        cap_entry["package"] = _pkg_m.group(1)
                input_caps.append(cap_entry)
            if input_caps:
                input_caps.sort(key=lambda c: -c["farads"])
                reg["input_capacitors"] = input_caps

        # Detect compensation caps on the FB net
        fb_net = reg.get("fb_net")
        if fb_net and fb_net in ctx.nets:
            comp_caps = []
            for p in ctx.nets[fb_net]["pins"]:
                cref = p["component"]
                if cref == reg_ref:
                    continue
                comp = ctx.comp_lookup.get(cref)
                if not comp or comp["type"] != "capacitor":
                    continue
                c_val = ctx.parsed_values.get(cref)
                if not c_val or c_val <= 0:
                    continue
                # Check what else this cap connects to (output rail = feed-forward, GND = compensation)
                n1, n2 = ctx.get_two_pin_nets(cref)
                other_net = n2 if n1 == fb_net else n1
                comp_caps.append({
                    "ref": cref,
                    "value": comp["value"],
                    "farads": c_val,
                    "other_net": other_net,
                    "role": "feed_forward" if other_net == output_rail else
                            "compensation" if ctx.is_ground(other_net) else "unknown",
                })
            if comp_caps:
                reg["compensation_capacitors"] = comp_caps


def _estimate_regulator_dissipation(ctx: AnalysisContext, power_regulators: list[dict]) -> None:
    """Add a power_dissipation estimate to each regulator, in place: an LDO whose input rail
    exceeds its Vout in magnitude (both of one sign), and a switching regulator."""
    # Estimate power dissipation for LDO regulators
    for reg in power_regulators:
        topology = reg.get("topology", "")
        vin_rail = reg.get("input_rail")
        vout = reg.get("estimated_vout")
        v_cfg = ctx.config_rail_voltage(reg.get("output_rail"))
        if v_cfg is not None:
            vout = v_cfg
        if topology == "LDO" and vin_rail and vout:
            vin = ctx.rail_voltage_or(vin_rail, _infer_rail_voltage)
            # A negative LDO (-12 V in, -5 V out) drops |Vin| - |Vout|; both rails share a sign.
            if vin and vin * vout > 0 and abs(vin) > abs(vout):
                dropout = abs(vin) - abs(vout)
                # Estimate load current from output cap total (heuristic:
                # ~100mA per 10µF of output capacitance is a rough proxy)
                output_caps = reg.get("output_capacitors", [])
                total_cout = sum(c.get("farads", 0) for c in output_caps)
                # Conservative estimate: assume typical load from cap sizing
                estimated_iout_a = min(total_cout * 1e4, 1.0) if total_cout > 0 else 0.1
                reg["power_dissipation"] = {
                    "vin_estimated_V": vin,
                    "vout_V": vout,
                    "dropout_V": round(dropout, 3),
                    "estimated_iout_A": round(estimated_iout_a, 3),
                    "estimated_pdiss_W": round(dropout * estimated_iout_a, 3),
                    "_iout_provenance": {
                        "source": "output_cap_proxy",
                        "confidence": "heuristic",
                        "basis": f"total_cout_{total_cout*1e6:.0f}uF",
                    },
                }
        elif topology == "switching" and vout:
            vin = ctx.rail_voltage_or(vin_rail, _infer_rail_voltage)
            if vin and vin > 0:
                # Estimate load current from output cap total (same heuristic as LDO,
                # but cap at 2.0A for switching regulators)
                output_caps = reg.get("output_capacitors", [])
                total_cout = sum(c.get("farads", 0) for c in output_caps)
                estimated_iout_a = min(total_cout * 1e4, 2.0) if total_cout > 0 else 0.2

                # Determine sub-topology from part name/lib_id keywords
                lib_val_lower = (reg.get("lib_id", "") + " " + reg.get("value", "")).lower()
                if "buck-boost" in lib_val_lower or "buck_boost" in lib_val_lower \
                        or "sepic" in lib_val_lower or "inverting" in lib_val_lower:
                    sw_type = "buck-boost"
                    efficiency = 0.78
                elif "boost" in lib_val_lower or "step-up" in lib_val_lower \
                        or "step_up" in lib_val_lower or "step up" in lib_val_lower:
                    sw_type = "boost"
                    efficiency = 0.80
                elif "buck" in lib_val_lower or "step-down" in lib_val_lower \
                        or "step_down" in lib_val_lower or "step down" in lib_val_lower:
                    sw_type = "buck"
                    efficiency = 0.85
                else:
                    # Fall back to vin/vout relationship
                    if vout < 0:
                        sw_type = "buck-boost"  # inverting
                        efficiency = 0.78
                    elif vin > vout:
                        sw_type = "buck"
                        efficiency = 0.85
                    elif vin < vout:
                        sw_type = "boost"
                        efficiency = 0.80
                    else:
                        sw_type = "buck-boost"
                        efficiency = 0.78

                pout = abs(vout) * estimated_iout_a
                pin = pout / efficiency
                pdiss = pin - pout

                reg["power_dissipation"] = {
                    "vin_estimated_V": round(vin, 3),
                    "vout_V": round(vout, 3),
                    "efficiency_assumed": efficiency,
                    "estimated_iout_A": round(estimated_iout_a, 3),
                    "estimated_pdiss_W": round(pdiss, 3),
                    "topology": "switching",
                    "sub_topology": sw_type,
                    "_iout_provenance": {
                        "source": "output_cap_proxy",
                        "confidence": "heuristic",
                        "basis": f"total_cout_{total_cout*1e6:.0f}uF",
                    },
                    "_pdiss_provenance": {
                        "source": "topology_default_efficiency",
                        "confidence": "heuristic",
                        "basis": f"efficiency_{efficiency:.0%}_assumed",
                    },
                }


def detect_integrated_ldos(ctx: AnalysisContext, power_regulators: list[dict]) -> list[dict]:
    """Detect ICs with integrated LDOs that output to power nets."""
    _ldo_pin_names = frozenset({
        "VREGOUT", "VREG", "LDO_OUT", "REGOUT", "REG_OUT",
        "VOUT_LDO", "VLDO", "V1P8OUT", "V3P3OUT", "VCOREOUT",
        "VDDOUT", "VREG18", "VREG33", "VREG_OUT",
    })
    existing_refs = {r["ref"] for r in power_regulators}
    integrated = []

    # Non-regulator ICs with VREG decoupling pins
    _non_reg_ic_keywords = ("usb_hub", "hub", "cy7c65", "usb2512", "usb2514",
                            "tusb8", "usb3503", "fe1.1", "gl850",
                            "fpga", "cpld", "mcu", "microcontroller",
                            "stm32", "esp32", "nrf5", "atmega", "pic",
                            "ethernet", "phy", "codec", "audio")
    for ic in [c for c in ctx.components if c["type"] == "ic"]:
        ref = ic["reference"]
        if ref in existing_refs:
            continue
        lib_val_lower = (ic.get("lib_id", "") + " " + ic.get("value", "")).lower()
        if any(k in lib_val_lower for k in _non_reg_ic_keywords):
            continue
        for pnum, (net_name, _) in ctx.ref_pins.get(ref, {}).items():
            if not net_name:
                continue
            # Get pin name
            pin_name = ""
            if net_name in ctx.nets:
                for p in ctx.nets[net_name]["pins"]:
                    if p["component"] == ref and p["pin_number"] == pnum:
                        pin_name = p.get("pin_name", "").upper()
                        break
            # Check pin name against LDO output patterns
            pn_clean = pin_name.replace(" ", "").replace("/", "_")
            if pn_clean in _ldo_pin_names or pin_name in _ldo_pin_names:
                if ctx.is_power_net(net_name) and not ctx.is_ground(net_name):
                    integrated.append({
                        "ref": ref,
                        "value": ic.get("value", ""),
                        "lib_id": ic.get("lib_id", ""),
                        "topology": "integrated_ldo",
                        "output_rail": net_name,
                        "output_pin": pin_name,
                        "detector": "detect_integrated_ldos",
                        "rule_id": "IL-DET",
                        "category": "power_management",
                        "severity": "info",
                        "confidence": "deterministic",
                        "evidence_source": "topology",
                        "summary": f"Integrated LDO {ref}",
                        "description": f"IC with integrated LDO output ({pin_name} → {net_name})",
                        "components": [ref],
                        "nets": [],
                        "pins": [],
                        "recommendation": "",
                        "report_context": {"section": "Power Management", "impact": "", "standard_ref": ""},
                        "provenance": make_provenance("ildo_vreg_pin", "heuristic", [ref]),
                    })
                    existing_refs.add(ref)
                    break

    return integrated


def detect_protection_devices(ctx: AnalysisContext) -> list[dict]:
    """Detect protection devices (TVS, ESD, Schottky, fuses, etc.)."""
    protection_devices: list[dict] = []
    protection_types = ("diode", "varistor", "surge_arrester")
    tvs_keywords = ("tvs", "esd", "pesd", "prtr", "usblc", "sp0", "tpd", "ip4", "rclamp",
                     "smaj", "smbj", "p6ke", "1.5ke", "lesd", "nup")
    schottky_keywords = ("schottky", "d_schottky")

    for comp in ctx.components:
        if comp["type"] not in protection_types:
            continue
        val = comp.get("value", "").lower()
        lib = comp.get("lib_id", "").lower()
        desc = comp.get("description", "").lower()

        is_tvs = comp["type"] == "diode" and any(k in val or k in lib for k in tvs_keywords)
        is_schottky = comp["type"] == "diode" and any(k in lib or k in desc for k in schottky_keywords)
        is_non_diode_protection = comp["type"] in ("varistor", "surge_arrester")

        if comp["type"] == "diode" and not is_tvs and not is_schottky:
            continue

        # Multi-pin protection diodes (PRTR5V0U2X, etc.) — handle like ESD ICs
        comp_pins = comp.get("pins", [])
        if len(comp_pins) > 2 and is_tvs:
            if any(p["ref"] == comp["reference"] for p in protection_devices):
                continue
            protected = []
            for pin in comp_pins:
                net_name, _ = ctx.pin_net.get((comp["reference"], pin["number"]), (None, None))
                if net_name and not ctx.is_power_net(net_name) and not ctx.is_ground(net_name):
                    protected.append(net_name)
            # One entry per component, collect all protected nets
            if protected:
                sorted_nets = sorted(set(protected))
                protection_devices.append({
                    "ref": comp["reference"],
                    "value": comp.get("value", ""),
                    "type": "esd_ic",
                    "protected_net": sorted_nets[0],
                    "protected_nets": sorted_nets,
                    "clamp_net": None,
                    "detector": "detect_protection_devices",
                    "rule_id": "PD-DET",
                    "category": "protection",
                    "severity": "info",
                    "confidence": "deterministic",
                    "evidence_source": "topology",
                    "summary": f"Protection {comp['reference']} esd_ic",
                    "description": "Multi-pin ESD protection array detected",
                    "components": [comp["reference"]],
                    "nets": [],
                    "pins": [],
                    "recommendation": "",
                    "report_context": {"section": "Protection", "impact": "", "standard_ref": ""},
                    "provenance": make_provenance("prot_esd_array", "deterministic", [comp["reference"]]),
                })
            continue

        d_n1, d_n2 = ctx.get_two_pin_nets(comp["reference"])
        if not d_n1 or not d_n2:
            continue

        protected_net = None
        prot_type = comp["type"]

        if is_schottky and not is_tvs:
            if ctx.is_power_net(d_n1) and (ctx.is_ground(d_n2) or ctx.is_power_net(d_n2)):
                protected_net = d_n1
                prot_type = "reverse_polarity"
            elif ctx.is_power_net(d_n2) and (ctx.is_ground(d_n1) or ctx.is_power_net(d_n1)):
                protected_net = d_n2
                prot_type = "reverse_polarity"
        else:
            if ctx.is_ground(d_n1) and not ctx.is_ground(d_n2):
                protected_net = d_n2
            elif ctx.is_ground(d_n2) and not ctx.is_ground(d_n1):
                protected_net = d_n1
            elif ctx.is_power_net(d_n1) and not ctx.is_power_net(d_n2):
                protected_net = d_n2
            elif ctx.is_power_net(d_n2) and not ctx.is_power_net(d_n1):
                protected_net = d_n1

        if protected_net:
            # Deduplicate multi-unit TVS arrays (same ref, different units)
            if any(p["ref"] == comp["reference"] for p in protection_devices):
                continue
            protection_devices.append({
                "ref": comp["reference"],
                "value": comp.get("value", ""),
                "type": prot_type,
                "protected_net": protected_net,
                "clamp_net": d_n1 if protected_net == d_n2 else d_n2,
                "detector": "detect_protection_devices",
                "rule_id": "PD-DET",
                "category": "protection",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Protection {comp['reference']} {prot_type}",
                "description": f"Protection device ({prot_type}) on {protected_net}",
                "components": [comp["reference"]],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Protection", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("prot_tvs", "deterministic", [comp["reference"]]),
            })

    # Also detect varistors and surge arresters (already typed correctly)
    for comp in ctx.components:
        if comp["type"] in ("varistor", "surge_arrester"):
            # Avoid duplicates
            if any(p["ref"] == comp["reference"] for p in protection_devices):
                continue
            # Try standard 2-pin first, then fall back to scanning
            # all pin_net entries (Eagle imports use P$1/P$2/P$3 pin names)
            d_n1, d_n2 = ctx.get_two_pin_nets(comp["reference"])
            if not d_n1 or not d_n2:
                comp_nets = {net for net, _ in ctx.ref_pins.get(comp["reference"], {}).values() if net}
                comp_nets = [n for n in comp_nets
                             if not ctx.is_ground(n) or len(comp_nets) <= 2]
                if len(comp_nets) >= 2:
                    nets_list = sorted(comp_nets)
                    d_n1, d_n2 = nets_list[0], nets_list[1]
                else:
                    continue
            protected_net = d_n1 if not ctx.is_ground(d_n1) else d_n2
            protection_devices.append({
                "ref": comp["reference"],
                "value": comp.get("value", ""),
                "type": comp["type"],
                "protected_net": protected_net,
                "clamp_net": d_n1 if protected_net == d_n2 else d_n2,
                "detector": "detect_protection_devices",
                "rule_id": "PD-DET",
                "category": "protection",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Protection {comp['reference']} {comp['type']}",
                "description": f"Protection device ({comp['type']}) on {protected_net}",
                "components": [comp["reference"]],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Protection", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("prot_varistor", "deterministic", [comp["reference"]]),
            })

    # PTC fuses / polyfuses used as overcurrent protection
    for comp in ctx.components:
        if comp["type"] != "fuse":
            continue
        if any(p["ref"] == comp["reference"] for p in protection_devices):
            continue
        d_n1, d_n2 = ctx.get_two_pin_nets(comp["reference"])
        if not d_n1 or not d_n2:
            continue
        protected_net = None
        if ctx.is_power_net(d_n1) and not ctx.is_power_net(d_n2) and not ctx.is_ground(d_n2):
            protected_net = d_n2
        elif ctx.is_power_net(d_n2) and not ctx.is_power_net(d_n1) and not ctx.is_ground(d_n1):
            protected_net = d_n1
        elif ctx.is_power_net(d_n1) and ctx.is_power_net(d_n2):
            protected_net = d_n2
        if protected_net:
            protection_devices.append({
                "ref": comp["reference"],
                "value": comp.get("value", ""),
                "type": "fuse",
                "protected_net": protected_net,
                "clamp_net": d_n1 if protected_net == d_n2 else d_n2,
                "detector": "detect_protection_devices",
                "rule_id": "PD-DET",
                "category": "protection",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Protection {comp['reference']} fuse",
                "description": f"Fuse/polyfuse protection on {protected_net}",
                "components": [comp["reference"]],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Protection", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("prot_fuse", "deterministic", [comp["reference"]]),
            })

    # ---- IC-based ESD Protection ----
    # Expanded keywords + Power_Protection library check
    esd_ic_keywords = ("usblc", "tpd", "prtr", "ip42", "sp05", "esda",
                       "pesd", "nup4", "sn65220", "dtc11", "sp72",
                       "tvs18", "tvs1", "ecmf", "cdsot", "smda", "rclamp")
    for comp in ctx.components:
        if comp["type"] != "ic":
            continue
        val = comp.get("value", "").lower()
        lib = comp.get("lib_id", "").lower()
        is_protection_lib = "power_protection:" in lib
        if not (any(k in val or k in lib for k in esd_ic_keywords) or is_protection_lib):
            continue
        if any(p["ref"] == comp["reference"] for p in protection_devices):
            continue
        protected = []
        for pin in comp.get("pins", []):
            net_name, _ = ctx.pin_net.get((comp["reference"], pin["number"]), (None, None))
            if net_name and not ctx.is_power_net(net_name) and not ctx.is_ground(net_name):
                protected.append(net_name)
        # One entry per component, collect all protected nets
        if protected:
            sorted_nets = sorted(set(protected))
            protection_devices.append({
                "ref": comp["reference"],
                "value": comp.get("value", ""),
                "type": "esd_ic",
                "protected_net": sorted_nets[0],
                "protected_nets": sorted_nets,
                "clamp_net": None,
                "detector": "detect_protection_devices",
                "rule_id": "PD-DET",
                "category": "protection",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Protection {comp['reference']} esd_ic",
                "description": "IC-based ESD protection device detected",
                "components": [comp["reference"]],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Protection", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("prot_ic_based", "deterministic", [comp["reference"]]),
            })

    return protection_devices


def _opamp_gain_adjustable(ctx: AnalysisContext, opamp_ref: str, out_net: str, neg_net: str,
                           gain_parts: set[str], leg_ref: str | None) -> bool:
    """True when a potentiometer sets the gain, or another resistor bridges the inverting
    input to the output or to the gain leg's far net: the stage has no single gain."""
    if any(_is_potentiometer(ctx, r) for r in gain_parts):
        return True
    leg_far = None
    if leg_ref:
        leg_far = next((n for n in _part_nets(ctx, leg_ref) if n != neg_net), None)
    for p in ctx.nets.get(neg_net, {}).get("pins", []):
        r = p["component"]
        comp = ctx.comp_lookup.get(r)
        if r == opamp_ref or r in gain_parts or not comp or comp.get("dnp"):
            continue
        if comp["type"] != "resistor" and not (comp["type"] == "varistor" and _is_potentiometer(ctx, r)):
            continue
        nets = _part_nets(ctx, r)
        if out_net in nets or (leg_far is not None and leg_far in nets):
            return True
    return False


def detect_opamp_circuits(ctx: AnalysisContext) -> list[dict]:
    """Detect op-amp gain stage configurations."""
    # EQ-071: G = 1+Rf/Ri or -Rf/Ri; G_dB = 20log₁₀|G| (opamp gain)
    opamp_circuits: list[dict] = []
    opamp_lib_keywords = ("amplifier_operational", "op_amp", "opamp")
    opamp_value_keywords = ("opa", "lm358", "lm324", "mcp6", "ad8", "tl07", "tl08",
                            "ne5532", "lf35", "lt623", "ths", "ada4",
                            "ina10", "ina11", "ina12", "ina13",
                            "ncs3", "lmc7", "lmv3", "max40", "max44",
                            "tsc10", "mcp60", "mcp61", "mcp65")

    seen_opamp_units = set()  # (ref, unit) to avoid multi-unit duplicates
    for ic in [c for c in ctx.components if c["type"] == "ic"]:
        lib = ic.get("lib_id", "").lower()
        val = ic.get("value", "").lower()
        desc = ic.get("description", "").lower()
        lib_part = lib.split(":")[-1] if ":" in lib else ""
        match_sources = [val, lib_part]
        if not (any(k in lib for k in opamp_lib_keywords) or
                any(s.startswith(k) for k in opamp_value_keywords for s in match_sources) or
                any(k in desc for k in ("opamp", "op-amp", "op amp", "operational amplifier", "instrumentation"))):
            continue

        # Exclude power/current monitors (INA2xx, INA8xx) that match
        # via description keywords like "instrumentation"
        _pm_val = (val + " " + lib_part).lower()
        if any(_pm_val.startswith(k) for k in ("ina2", "ina8", "ina90")):
            continue

        ref = ic["reference"]
        unit = ic.get("unit", 1)
        if (ref, unit) in seen_opamp_units:
            continue
        seen_opamp_units.add((ref, unit))

        # For multi-unit op-amps, restrict to this unit's pins.
        unit_pin_nums = None
        lib_id = ic.get("lib_id", "")
        sym_def = ctx.lib_symbols.get(lib_id)
        if sym_def and sym_def.get("unit_pins") and unit in sym_def["unit_pins"]:
            unit_pin_nums = {p["number"] for p in sym_def["unit_pins"][unit]}
            if 0 in sym_def["unit_pins"]:
                unit_pin_nums |= {p["number"] for p in sym_def["unit_pins"][0]}

        # Find op-amp pins: +IN, -IN, OUT
        pos_in = None
        neg_in = None
        out_pin = None
        for pnum, (net, _) in ctx.ref_pins.get(ref, {}).items():
            if not net:
                continue
            if unit_pin_nums is not None and pnum not in unit_pin_nums:
                continue
            pin_name = ""
            if net in ctx.nets:
                for p in ctx.nets[net]["pins"]:
                    if p["component"] == ref and p["pin_number"] == pnum:
                        pin_name = p.get("pin_name", "").upper()
                        break
            if not pin_name:
                continue
            pn = pin_name.replace(" ", "")
            if pn in ("+", "+IN", "IN+", "INP", "V+IN", "NONINVERTING",
                      "NON-INV", "NON-INVERTING", "NI") or \
               (pn.startswith("+") and "IN" in pn):
                pos_in = (pin_name, net, pnum)
            elif pn in ("-", "-IN", "IN-", "INM", "V-IN", "INVERTING",
                         "INV", "INV-IN") or \
                 (pn.startswith("-") and "IN" in pn):
                neg_in = (pin_name, net, pnum)
            elif pn in _VOUT_PIN_NAMES:
                out_pin = (pin_name, net, pnum)
            elif pn in ("V+", "V-", "VCC", "VDD", "VEE", "VSS", "VS+", "VS-"):
                continue
            else:
                pin_type = ""
                if net in ctx.nets:
                    for p in ctx.nets[net]["pins"]:
                        if p["component"] == ref and p["pin_number"] == pnum:
                            pin_type = p.get("pin_type", "")
                            break
                if pin_type == "output" and not out_pin:
                    out_pin = (pin_name, net, pnum)
                elif pin_type == "input":
                    if not pos_in:
                        pos_in = (pin_name, net, pnum)
                    elif not neg_in:
                        neg_in = (pin_name, net, pnum)

        # Legacy format fallback — no pin data but keyword match confirmed
        if pos_in is None and neg_in is None and out_pin is None:
            opamp_circuits.append({
                "reference": ref,
                "value": ic.get("value", ""),
                "lib_id": ic.get("lib_id", ""),
                "configuration": "unknown",
                "unit": unit,
                "detector": "detect_opamp_circuits",
                "rule_id": "OA-DET",
                "category": "analog",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "summary": f"Op-amp {ref} unknown",
                "description": "Op-amp detected (no pin data available)",
                "components": [ref],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Analog", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("opamp_topology", "deterministic", [ref]),
            })
            continue

        if not out_pin or not neg_in:
            continue

        out_net = out_pin[1]
        neg_net = neg_in[1]
        pos_net = pos_in[1] if pos_in else None

        # Find feedback resistor; *_members = the parallel group a part stands for
        rf_ref = None
        rf_val = None
        rf_members: list[str] = []
        cf_members: list[str] = []
        rf_chain: list[str] = []  # a 2-hop feedback path: both of its parts
        if out_net in ctx.nets and neg_net != out_net:
            out_comps = {p["component"] for p in ctx.nets[out_net]["pins"] if p["component"] != ref}
            neg_comps = {p["component"] for p in ctx.nets[neg_net]["pins"] if p["component"] != ref}
            fb_resistors = out_comps & neg_comps
            for fb_ref in sorted(fb_resistors):
                comp = ctx.comp_lookup.get(fb_ref)
                if comp and comp["type"] == "resistor" and fb_ref in ctx.parsed_values:
                    # Verify direct connection — one pin on out_net, other on neg_net
                    fb_n1, fb_n2 = ctx.get_two_pin_nets(fb_ref)
                    if {fb_n1, fb_n2} == {out_net, neg_net}:
                        if group_value(ctx, fb_ref) is None:
                            continue
                        rf_members = group_members(ctx, fb_ref)
                        rf_ref, rf_val = rf_members[0], group_value(ctx, fb_ref)
                        break

            # Capacitor feedback (integrator/compensator)
            cf_ref = None
            cf_val = None
            fb_caps = out_comps & neg_comps
            for fb_cref in sorted(fb_caps):
                comp = ctx.comp_lookup.get(fb_cref)
                if comp and comp["type"] == "capacitor" and fb_cref in ctx.parsed_values:
                    # Verify direct connection
                    fb_n1, fb_n2 = ctx.get_two_pin_nets(fb_cref)
                    if {fb_n1, fb_n2} == {out_net, neg_net}:
                        if group_value(ctx, fb_cref) is None:
                            continue
                        cf_members = group_members(ctx, fb_cref)
                        cf_ref, cf_val = cf_members[0], group_value(ctx, fb_cref)
                        break

            # 2-hop feedback
            if not rf_ref:
                for out_comp_ref in sorted(out_comps):
                    oc = ctx.comp_lookup.get(out_comp_ref)
                    if not oc or oc["type"] not in ("resistor", "capacitor"):
                        continue
                    o_n1, o_n2 = ctx.get_two_pin_nets(out_comp_ref)
                    if not o_n1 or not o_n2:
                        continue
                    mid = o_n2 if o_n1 == out_net else o_n1
                    # Also skip if mid == neg_net (degenerate 2-hop = direct path)
                    if mid in (out_net, neg_net) or ctx.is_ground(mid) or ctx.is_power_net(mid):
                        continue
                    if mid in ctx.nets:
                        mid_comps = {p["component"] for p in ctx.nets[mid]["pins"]
                                    if p["component"] != out_comp_ref}
                        fb_via_mid = mid_comps & neg_comps
                        for fb2 in sorted(fb_via_mid):
                            c2 = ctx.comp_lookup.get(fb2)
                            if c2 and c2["type"] in ("resistor", "capacitor"):
                                if oc["type"] == "resistor" and out_comp_ref in ctx.parsed_values:
                                    rf_ref = out_comp_ref
                                    rf_val = ctx.parsed_values[out_comp_ref]
                                    rf_members = [rf_ref]
                                    rf_chain = [out_comp_ref, fb2]
                                elif c2["type"] == "resistor" and fb2 in ctx.parsed_values:
                                    rf_ref = fb2
                                    rf_val = ctx.parsed_values[fb2]
                                    rf_members = [rf_ref]
                                    rf_chain = [out_comp_ref, fb2]
                                break
                    if rf_ref:
                        break
        else:
            cf_ref = None
            cf_val = None

        # Input resistor (- to a signal net) and ground leg Rg (- to ground). A resistor
        # from - to a power rail biases the input; it is neither.
        ri_ref = ri_val = rg_ref = rg_val = None
        ri_members: list[str] = []
        rg_members: list[str] = []
        if neg_net in ctx.nets:
            for p in ctx.nets[neg_net]["pins"]:
                if p["component"] == ref or p["component"] in rf_members:
                    continue
                comp = ctx.comp_lookup.get(p["component"])
                if comp and comp["type"] == "resistor" and p["component"] in ctx.parsed_values:
                    r_val = group_value(ctx, p["component"])
                    if r_val is None:
                        continue
                    r_members = group_members(ctx, p["component"])
                    r_n1, r_n2 = ctx.get_two_pin_nets(p["component"])
                    if _is_potentiometer(ctx, p["component"]) and len(_part_nets(ctx, p["component"])) == 2:
                        r_n1, r_n2 = _part_nets(ctx, p["component"])
                    other = r_n2 if r_n1 == neg_net else r_n1
                    if other == out_net:
                        continue
                    if not ctx.is_power_net(other) and not ctx.is_ground(other):
                        if ri_ref is None:
                            ri_ref, ri_val, ri_members = r_members[0], r_val, r_members
                    elif ctx.is_ground(other) and rg_ref is None and not _is_three_net_pot(ctx, p["component"]):
                        rg_ref, rg_val, rg_members = r_members[0], r_val, r_members

        # Determine configuration
        config = "unknown"
        gain = None
        if out_net == neg_net:
            config = "buffer"
            gain = 1.0
        elif (rf_ref and rf_val and rg_val and not ri_ref and pos_net and pos_net != neg_net
              and not ctx.is_power_net(pos_net) and not ctx.is_ground(pos_net)):
            config = "non_inverting"
            gain = 1.0 + rf_val / rg_val
            # The ground leg is recorded as input_resistor, where SPICE and what_if read it
            ri_ref, ri_val, ri_members = rg_ref, rg_val, rg_members
        elif rf_ref and ri_ref and ri_val and rf_val:
            config = "inverting"
            gain = -rf_val / ri_val
        elif cf_ref and not rf_ref and ri_ref:
            config = "integrator"
        elif cf_ref and rf_ref:
            # Distinguish TIA from compensator.
            # TIA: feedback R >> input R (transimpedance gain = Rf)
            # Compensator: similar-value R+C for loop compensation
            if ri_ref and ri_val and rf_val and ri_val > 0 and rf_val / ri_val > 10:
                config = "transimpedance"
            elif not ri_ref:
                # No input resistor at all — classic TIA topology
                # (photodiode or sensor connected directly to inverting input)
                config = "transimpedance"
            else:
                config = "compensator"
        elif rf_ref and not ri_ref:
            config = "transimpedance_or_buffer"
        elif not rf_ref:
            config = "comparator_or_open_loop"

        if gain is not None and config != "buffer" and _opamp_gain_adjustable(
                ctx, ref, out_net, neg_net, set(rf_chain or rf_members) | set(ri_members), ri_ref):
            gain = None

        entry = {
            "reference": ref,
            "unit": unit,
            "value": ic["value"],
            "lib_id": ic.get("lib_id", ""),
            "configuration": config,
            "output_net": out_net,
            "inverting_input_net": neg_net,
            "non_inverting_input_net": pos_net,
        }
        if gain is not None:
            entry["gain"] = round(gain, 3)
            entry["gain_dB"] = round(20 * math.log10(abs(gain)), 1) if gain != 0 else None
        for key, part_ref, unit_key, part_val, members in (
                ("feedback_resistor", rf_ref, "ohms", rf_val, rf_members),
                ("feedback_capacitor", cf_ref, "farads", cf_val, cf_members),
                ("input_resistor", ri_ref, "ohms", ri_val, ri_members)):
            if part_ref:
                entry[key] = {"ref": part_ref, unit_key: part_val}
                if len(members) > 1:
                    entry[key]["parallel_refs"] = list(members)

        # ---- Advanced opamp checks ----
        warnings = []

        # Bias current path check
        if pos_net and config not in ("comparator_or_open_loop", "unknown"):
            pos_net_info = ctx.nets.get(pos_net, {})
            has_dc_path = False
            has_cap_only = False
            for p in pos_net_info.get("pins", []):
                if p["component"] == ref:
                    continue
                neighbor = ctx.comp_lookup.get(p["component"])
                if not neighbor:
                    continue
                if neighbor["type"] == "resistor":
                    has_dc_path = True
                    break
                elif neighbor["type"] in ("ic", "connector"):
                    has_dc_path = True
                    break
                elif neighbor["type"] == "capacitor":
                    has_cap_only = True
            if pos_net and (ctx.is_power_net(pos_net) or ctx.is_ground(pos_net)):
                has_dc_path = True
            if has_cap_only and not has_dc_path:
                warnings.append("Non-inverting input AC-coupled with no DC bias path — "
                                "input bias current has no return path")

        # Output capacitive loading check
        if out_net and config not in ("comparator_or_open_loop", "unknown"):
            out_net_info = ctx.nets.get(out_net, {})
            for p in out_net_info.get("pins", []):
                if p["component"] == ref:
                    continue
                neighbor = ctx.comp_lookup.get(p["component"])
                if not neighbor or neighbor["type"] != "capacitor":
                    continue
                cap_val = neighbor.get("parsed_value") or parse_value(neighbor.get("value", ""))
                if cap_val and cap_val > 100e-12:
                    formatted = f"{cap_val*1e9:.0f}nF" if cap_val >= 1e-9 else f"{cap_val*1e12:.0f}pF"
                    warnings.append(f"Capacitive load {neighbor['reference']} ({formatted}) on "
                                    f"output — verify opamp stability with this load")

        # High-impedance feedback warning
        if rf_ref and rf_val and rf_val > 1e6:
            formatted_r = f"{rf_val/1e6:.1f}MΩ" if rf_val >= 1e6 else f"{rf_val/1e3:.0f}kΩ"
            warnings.append(f"High-impedance feedback ({rf_ref}={formatted_r}) — "
                            f"sensitive to PCB leakage and parasitic capacitance")

        if warnings:
            entry["warnings"] = warnings

        # Dedup
        dedup_key = (ref, out_net, neg_net)
        if dedup_key not in seen_opamp_units:
            seen_opamp_units.add(dedup_key)
            entry["detector"] = "detect_opamp_circuits"
            entry["rule_id"] = "OA-DET"
            entry["category"] = "analog"
            entry["severity"] = "info"
            entry["confidence"] = "deterministic"
            entry["evidence_source"] = "topology"
            entry["summary"] = f"Op-amp {ref} {config}"
            entry["description"] = f"Op-amp circuit in {config} configuration"
            entry["components"] = [ref]
            entry["nets"] = []
            entry["pins"] = []
            entry["recommendation"] = ""
            entry["report_context"] = {"section": "Analog", "impact": "", "standard_ref": ""}
            entry["provenance"] = make_provenance("opamp_topology", "deterministic", [ref])
            opamp_circuits.append(entry)

    # ---- Unused channel detection for multi-channel opamps ----
    units_by_ref = {}
    for oa in opamp_circuits:
        units_by_ref.setdefault(oa["reference"], set()).add(oa.get("unit", 1))

    for ic in [c for c in ctx.components if c["type"] == "ic"]:
        ref = ic["reference"]
        if ref not in units_by_ref:
            continue
        lib = ic.get("lib_id", "").lower()
        val = ic.get("value", "").lower()
        expected_units = None
        if "quad" in lib or "quad" in val or any(q in val for q in ("lm324", "tl074", "tl084", "mcp6004", "opa4")):
            expected_units = 4
        elif "dual" in lib or "dual" in val or any(d in val for d in ("lm358", "tl072", "tl082", "ne5532", "mcp6002", "opa2")):
            expected_units = 2
        if expected_units is None:
            continue
        used_units = units_by_ref[ref]
        if len(used_units) < expected_units:
            unused = sorted(set(range(1, expected_units + 1)) - used_units)
            if unused:
                inputs_floating = False
                for u in unused:
                    for pin in ic.get("pins", []):
                        if pin.get("unit") == u:
                            pname = pin.get("name", "").upper()
                            if any(k in pname for k in ("+IN", "INP", "IN+", "NON_INV")):
                                net_name, _ = ctx.pin_net.get((ref, pin["number"]), (None, None))
                                if not net_name:
                                    inputs_floating = True
                for oa in opamp_circuits:
                    if oa["reference"] == ref:
                        oa["unused_channels"] = unused
                        oa["unused_channel_status"] = "inputs_floating" if inputs_floating else "inputs_terminated"
                        if inputs_floating:
                            oa.setdefault("warnings", []).append(
                                f"Unused opamp channel(s) {unused} have floating inputs — "
                                f"tie inputs to a defined potential")
                        break

    return opamp_circuits


def detect_bridge_circuits(ctx: AnalysisContext) -> tuple[list[dict], set, dict]:
    """Detect gate driver / bridge topology.

    Returns (bridge_circuits, matched_fets, fet_pins).
    """
    bridge_circuits: list[dict] = []
    transistors = [c for c in ctx.components if c["type"] == "transistor"]

    # Build transistor pin map: ref -> {GATE: net, DRAIN: net, SOURCE: net}
    fet_pins = {}
    for t in transistors:
        ref = t["reference"]
        pins = {}
        for pnum, (net, _) in ctx.ref_pins.get(ref, {}).items():
            # Find pin name
            if net and net in ctx.nets:
                for p in ctx.nets[net]["pins"]:
                    if p["component"] == ref and p["pin_number"] == pnum:
                        pn = p.get("pin_name", "").upper()
                        pn_base = pn.rstrip("0123456789").rstrip("_")  # G1→G, D2→D, G_1→G
                        if "GATE" in pn or pn_base == "G":
                            pins["gate"] = net
                        elif "DRAIN" in pn or pn_base == "D":
                            pins.setdefault("drain", net)
                        elif "SOURCE" in pn or pn_base == "S":
                            pins.setdefault("source", net)
                        break
        if "gate" in pins and "drain" in pins and "source" in pins:
            fet_pins[ref] = {**pins, "value": t["value"], "lib_id": t.get("lib_id", "")}

    # Find half-bridge pairs
    matched = set()
    half_bridges = []
    for hi_ref, hi in fet_pins.items():
        if hi_ref in matched:
            continue
        for lo_ref, lo in fet_pins.items():
            if lo_ref == hi_ref or lo_ref in matched:
                continue
            if hi["source"] == lo["drain"]:
                mid_net = hi["source"]
                if ctx.is_power_net(hi["drain"]) or ctx.is_ground(lo["source"]):
                    half_bridges.append({
                        "high_side": hi_ref,
                        "low_side": lo_ref,
                        "output_net": mid_net,
                        "power_net": hi["drain"],
                        "ground_net": lo["source"],
                        "high_gate": hi["gate"],
                        "low_gate": lo["gate"],
                    })
                    matched.add(hi_ref)
                    matched.add(lo_ref)
                    break

    if half_bridges:
        n = len(half_bridges)
        if n == 1:
            topology = "half_bridge"
        elif n == 2:
            topology = "h_bridge"
        elif n == 3:
            topology = "three_phase"
        else:
            topology = f"{n}_phase"

        gate_nets = set()
        for hb in half_bridges:
            gate_nets.add(hb["high_gate"])
            gate_nets.add(hb["low_gate"])
        driver_ics = set()
        for gn in gate_nets:
            if gn in ctx.nets:
                for p in ctx.nets[gn]["pins"]:
                    comp = ctx.comp_lookup.get(p["component"])
                    if comp and comp["type"] == "ic":
                        driver_ics.add(p["component"])

        # Enrich half-bridge dicts with FET type info
        for hb in half_bridges:
            hi_info = fet_pins.get(hb["high_side"], {})
            lo_info = fet_pins.get(hb["low_side"], {})
            hi_lib = hi_info.get("lib_id", "").lower()
            lo_lib = lo_info.get("lib_id", "").lower()
            hb["high_side_type"] = "PMOS" if ("pmos" in hi_lib or "pch" in hi_lib) else "NMOS"
            hb["low_side_type"] = "PMOS" if ("pmos" in lo_lib or "pch" in lo_lib) else "NMOS"
            # Add gate resistor values if available
            for gate_key, gate_net in [("high_gate", hb["high_gate"]), ("low_gate", hb["low_gate"])]:
                if gate_net in ctx.nets:
                    for p in ctx.nets[gate_net]["pins"]:
                        comp = ctx.comp_lookup.get(p["component"])
                        if comp and comp["type"] == "resistor":
                            r_val = ctx.parsed_values.get(p["component"])
                            if r_val:
                                hb[gate_key + "_resistor"] = {"ref": p["component"], "ohms": r_val}
                                break

        _bridge_refs = [hb["high_side"] for hb in half_bridges] + [hb["low_side"] for hb in half_bridges]
        _driver_ics = sorted(driver_ics)
        _bridge_driver_ref = _driver_ics[0] if _driver_ics else None
        _bridge_summary_ref = _bridge_driver_ref or (_bridge_refs[0] if _bridge_refs else "")
        bridge_circuits.append({
            "topology": topology,
            "half_bridges": half_bridges,
            "driver_ics": _driver_ics,
            "driver_values": {ref: ctx.comp_lookup[ref]["value"] for ref in _driver_ics if ref in ctx.comp_lookup},
            "fet_values": {hb["high_side"]: fet_pins[hb["high_side"]]["value"] for hb in half_bridges},
            "detector": "detect_bridge_circuits",
            "rule_id": "BR-DET",
            "category": "power_switching",
            "severity": "info",
            "confidence": "deterministic",
            "evidence_source": "topology",
            "summary": f"Bridge/gate driver {_bridge_summary_ref}",
            "description": f"{topology} bridge circuit detected",
            "components": _bridge_refs + _driver_ics,
            "nets": [],
            "pins": [],
            "recommendation": "",
            "report_context": {"section": "Power Switching", "impact": "", "standard_ref": ""},
            "provenance": make_provenance("bridge_matched_fets", "deterministic", _bridge_refs),
        })

    return bridge_circuits, matched, fet_pins


_CLAMP_DIODE_WORDS = ("zener", "tvs", "smaj", "smbj", "smcj", "p6ke", "p4ke", "1.5ke",
                      "bzx", "bzt", "mmsz", "1n47", "1n52")
# 1N5333-1N5388 are zeners; 1N5391-1N5399 next to them are rectifiers.
_ZENER_1N53 = re.compile(r"1n53[3-8]\d")


def _is_clamp_diode(comp: dict) -> bool:
    """A zener or TVS by its value or lib_id."""
    text = (comp.get("value", "") + " " + comp.get("lib_id", "")).lower()
    return any(w in text for w in _CLAMP_DIODE_WORDS) or bool(_ZENER_1N53.search(text))


def _diode_terminal_nets(ctx: AnalysisContext, ref: str) -> tuple[str | None, str | None]:
    """(anode net, cathode net) of a two-pin diode whose pins are named A and K, else (None, None).

    Pins from the built-in fallback symbol (snapped to a wire or not) are not the drawn
    part's, so their names do not count.
    """
    pins = ctx.ref_pins.get(ref, {})
    pin_source = (ctx.comp_lookup.get(ref) or {}).get("_pin_source")
    if len(pins) != 2 or pin_source in ("builtin", "snapped_to_wire"):
        return None, None
    anode = cathode = None
    for pin_num, (net, _) in pins.items():
        name = ""
        for p in ctx.nets.get(net, {}).get("pins", []):
            if p["component"] == ref and p["pin_number"] == pin_num:
                name = (p.get("pin_name") or "").upper()
                break
        if name in ("A", "ANODE"):
            anode = net
        elif name in ("K", "CATHODE"):
            cathode = net
    if anode is None or cathode is None:
        return None, None
    return anode, cathode


def detect_transistor_circuits(ctx: AnalysisContext, matched_fets: set, fet_pins: dict) -> list[dict]:
    """Detect transistor circuit configurations (MOSFETs and BJTs)."""
    transistor_circuits: list[dict] = []
    transistors = [c for c in ctx.components if c["type"] == "transistor"]

    # Build BJT pin map too (base/collector/emitter)
    bjt_pins = {}
    for t in transistors:
        ref = t["reference"]
        if ref in fet_pins:
            continue  # Already mapped as FET
        pins = {}
        for pnum, (net, _) in ctx.ref_pins.get(ref, {}).items():
            if net and net in ctx.nets:
                for p in ctx.nets[net]["pins"]:
                    if p["component"] == ref and p["pin_number"] == pnum:
                        pn = p.get("pin_name", "").upper()
                        if pn in ("B", "BASE"):
                            pins["base"] = net
                        elif pn in ("C", "COLLECTOR"):
                            pins["collector"] = net
                        elif pn in ("E", "EMITTER"):
                            pins["emitter"] = net
                        break
        if len(pins) >= 2:
            bjt_pins[ref] = {**pins, "value": t["value"], "lib_id": t.get("lib_id", "")}

    # Analyze each FET
    for ref, pins in fet_pins.items():
        if ref in matched_fets:
            continue  # Skip bridge FETs, handled above
        comp = ctx.comp_lookup.get(ref, {})
        gate_net = pins.get("gate")
        drain_net = pins.get("drain")
        source_net = pins.get("source")

        # Detect P-channel vs N-channel from lib_id, ki_keywords, and value
        lib_lower = comp.get("lib_id", "").lower()
        val_lower = comp.get("value", "").lower()
        kw_lower = comp.get("keywords", "").lower()
        is_pchannel = any(k in lib_lower for k in
                         ("pmos", "p-channel", "p_channel", "pchannel", "q_pmos", "p_jfet"))
        if not is_pchannel:
            is_pchannel = any(k in kw_lower for k in
                             ("p-channel", "pchannel", "pmos", "p-mos", "p-mosfet"))
        if not is_pchannel:
            is_pchannel = any(k in val_lower for k in
                             ("pmos", "p-channel", "p_channel", "pchannel", "dmp"))
        if not is_pchannel:
            desc_lower = comp.get("description", "").lower()
            is_pchannel = any(k in desc_lower for k in
                             ("p-channel", "p-mosfet", "pmos", "p-mos"))

        # Gate drive analysis
        gate_comps = ctx.nq.components_on_net(gate_net, exclude_refs={ref}) if gate_net else []
        gate_ics = [c for c in gate_comps if c["type"] == "ic"]

        # When gate is on a power rail, don't enumerate all resistors
        # on that rail — only include resistors connecting to drain/source/ground.
        if gate_net and ctx.is_power_net(gate_net):
            gate_resistors = []
            for gc in gate_comps:
                if gc["type"] != "resistor":
                    continue
                r_n1, r_n2 = ctx.get_two_pin_nets(gc["reference"])
                other = r_n2 if r_n1 == gate_net else r_n1
                if other in (drain_net, source_net) or ctx.is_ground(other):
                    gate_resistors.append(gc)
        else:
            gate_resistors = [c for c in gate_comps if c["type"] == "resistor"]

        if not gate_resistors and gate_net and gate_net in ctx.nets:
            gate_pin_count = len(ctx.nets[gate_net].get("pins", []))
            if gate_pin_count <= 3:
                for gc in gate_comps:
                    if gc["type"] == "resistor":
                        gate_resistors.append(gc)

        gate_pulldown = None
        for gr in gate_resistors:
            r_n1, r_n2 = ctx.get_two_pin_nets(gr["reference"])
            other_net = r_n2 if r_n1 == gate_net else r_n1
            if ctx.is_ground(other_net) or (is_pchannel and ctx.is_power_net(other_net)):
                gate_pulldown = {
                    "reference": gr["reference"],
                    "value": gr["value"],
                }
                break

        # Drain load analysis
        drain_comps = ctx.nq.components_on_net(drain_net, exclude_refs={ref}) if drain_net else []

        if is_pchannel and ctx.is_power_net(source_net):
            load_type = _classify_load(ctx, drain_net, ref) if drain_net else "unknown"
            if load_type == "other" and drain_net:
                load_type = "high_side_switch"
        else:
            load_type = _classify_load(ctx, drain_net, ref) if drain_net else "unknown"

        # Flyback diode check
        has_flyback = False
        flyback_ref = None
        for dc in drain_comps:
            if dc["type"] == "diode":
                d_n1, d_n2 = ctx.get_two_pin_nets(dc["reference"])
                # Drain-to-source topology
                if (d_n1 == source_net and d_n2 == drain_net) or \
                   (d_n1 == drain_net and d_n2 == source_net):
                    has_flyback = True
                    flyback_ref = dc["reference"]
                    break
                # Drain-to-supply topology (low-side switch flyback)
                d_other = d_n2 if d_n1 == drain_net else (d_n1 if d_n2 == drain_net else None)
                if d_other and ctx.is_power_net(d_other) and not ctx.is_ground(d_other):
                    if not is_pchannel:
                        # A zener/TVS clamp is not a flyback diode, and a flyback diode
                        # has its cathode on the supply and its anode on the drain.
                        if _is_clamp_diode(ctx.comp_lookup.get(dc["reference"]) or dc):
                            continue
                        anode, cathode = _diode_terminal_nets(ctx, dc["reference"])
                        if anode is not None and (anode, cathode) != (drain_net, d_other):
                            continue
                    has_flyback = True
                    flyback_ref = dc["reference"]
                    break

        # Snubber check — detect R+C from drain to source via intermediate net
        has_snubber = False
        snubber_data = None
        for dc in drain_comps:
            if dc["type"] == "resistor":
                r_n1, r_n2 = ctx.get_two_pin_nets(dc["reference"])
                other = r_n2 if r_n1 == drain_net else r_n1
                if other and other != source_net and not ctx.is_power_net(other):
                    for sc in ctx.nq.components_on_net(other, exclude_refs={dc["reference"]}):
                        if sc["type"] == "capacitor":
                            c_n1, c_n2 = ctx.get_two_pin_nets(sc["reference"])
                            c_other = c_n2 if c_n1 == other else c_n1
                            if c_other == source_net:
                                has_snubber = True
                                r_ohms = ctx.parsed_values.get(dc["reference"])
                                c_farads = ctx.parsed_values.get(sc["reference"])
                                if r_ohms and c_farads and r_ohms > 0 and c_farads > 0:
                                    snubber_data = {
                                        "resistor_ref": dc["reference"],
                                        "resistor_ohms": r_ohms,
                                        "capacitor_ref": sc["reference"],
                                        "capacitor_farads": c_farads,
                                    }
                                break
            if has_snubber:
                break

        # Source sense resistor
        source_sense = None
        if source_net and not ctx.is_ground(source_net):
            source_comps = ctx.nq.components_on_net(source_net, exclude_refs={ref})
            for sc in source_comps:
                if sc["type"] == "resistor":
                    r_n1, r_n2 = ctx.get_two_pin_nets(sc["reference"])
                    other = r_n2 if r_n1 == source_net else r_n1
                    if ctx.is_ground(other):
                        pv = parse_value(sc["value"])
                        if pv is not None and pv <= 1.0:
                            source_sense = {
                                "reference": sc["reference"],
                                "value": sc["value"],
                                "ohms": pv,
                            }
                            break

        # Level shifter detection: N-channel with gate→power, pull-ups on
        # both source and drain to different power rails
        topology = None
        if not is_pchannel and gate_net and ctx.is_power_net(gate_net):
            source_comps_ls = ctx.nq.components_on_net(source_net, exclude_refs={ref}) if source_net else []
            drain_comps_ls = drain_comps
            src_pullup_rail = None
            drn_pullup_rail = None
            for sc in source_comps_ls:
                if sc["type"] == "resistor":
                    r_n1, r_n2 = ctx.get_two_pin_nets(sc["reference"])
                    other = r_n2 if r_n1 == source_net else r_n1
                    if ctx.is_power_net(other):
                        src_pullup_rail = other
                        break
            for dc in drain_comps_ls:
                if dc["type"] == "resistor":
                    r_n1, r_n2 = ctx.get_two_pin_nets(dc["reference"])
                    other = r_n2 if r_n1 == drain_net else r_n1
                    if ctx.is_power_net(other):
                        drn_pullup_rail = other
                        break
            if src_pullup_rail and drn_pullup_rail and src_pullup_rail != drn_pullup_rail:
                topology = "level_shifter"
                load_type = "level_shifter"

        # Detect JFET from lib_id/value
        _jfet_kw = ("jfet", "n_jfet", "p_jfet", "q_jfet",
                     "j310", "j271", "j270", "j174", "j175", "j176",
                     "mmbfj", "bf545", "bf546", "bf244", "bf256",
                     "2n5457", "2n5458", "2n5459", "2n3819", "2n4416")
        is_jfet = any(k in lib_lower or k in val_lower for k in _jfet_kw)

        _tr_type = "jfet" if is_jfet else "mosfet"
        circuit = {
            "reference": ref,
            "value": comp.get("value", ""),
            "lib_id": comp.get("lib_id", ""),
            "type": _tr_type,
            "is_pchannel": is_pchannel,
            "gate_net": gate_net,
            "drain_net": drain_net,
            "source_net": source_net,
            "drain_is_power": ctx.is_power_net(drain_net) or (is_pchannel and ctx.is_power_net(source_net)),
            "source_is_ground": ctx.is_ground(source_net),
            "source_is_power": ctx.is_power_net(source_net),
            "load_type": load_type,
            "gate_resistors": [{"reference": r["reference"], "value": r["value"]} for r in gate_resistors],
            "gate_driver_ics": [{"reference": ic["reference"], "value": ic["value"]} for ic in gate_ics],
            "gate_pulldown": gate_pulldown,
            "has_flyback_diode": has_flyback,
            "flyback_diode": flyback_ref,
            "has_snubber": has_snubber,
            "snubber_data": snubber_data,
            "source_sense_resistor": source_sense,
            "detector": "detect_transistor_circuits",
            "rule_id": "TR-DET",
            "category": "discrete_semiconductors",
            "severity": "info",
            "confidence": "deterministic",
            "evidence_source": "topology",
            "summary": f"Transistor {ref} {_tr_type}",
            "description": f"Transistor circuit ({_tr_type}) detected",
            "components": [ref],
            "nets": [],
            "pins": [],
            "recommendation": "",
            "report_context": {"section": "Discrete Semiconductors", "impact": "", "standard_ref": ""},
            "provenance": make_provenance("transistor_mosfet", "deterministic", [ref]),
        }
        if topology:
            circuit["topology"] = topology
        transistor_circuits.append(circuit)

    # Analyze each BJT
    for ref, pins in bjt_pins.items():
        comp = ctx.comp_lookup.get(ref, {})
        base_net = pins.get("base")
        collector_net = pins.get("collector")
        emitter_net = pins.get("emitter")

        # Base drive analysis
        base_comps = ctx.nq.components_on_net(base_net, exclude_refs={ref}) if base_net else []
        base_resistors = [c for c in base_comps if c["type"] == "resistor"]
        base_ics = [c for c in base_comps if c["type"] == "ic"]
        base_pulldown = None
        for br in base_resistors:
            r_n1, r_n2 = ctx.get_two_pin_nets(br["reference"])
            other_net = r_n2 if r_n1 == base_net else r_n1
            if ctx.is_ground(other_net) or other_net == emitter_net:
                base_pulldown = {
                    "reference": br["reference"],
                    "value": br["value"],
                }
                break

        # Collector load
        load_type = _classify_load(ctx, collector_net, ref) if collector_net else "unknown"

        # Emitter resistor (degeneration)
        emitter_resistor = None
        if emitter_net and not ctx.is_ground(emitter_net):
            emitter_comps = ctx.nq.components_on_net(emitter_net, exclude_refs={ref})
            for ec in emitter_comps:
                if ec["type"] == "resistor":
                    r_n1, r_n2 = ctx.get_two_pin_nets(ec["reference"])
                    other = r_n2 if r_n1 == emitter_net else r_n1
                    if ctx.is_ground(other):
                        emitter_resistor = {
                            "reference": ec["reference"],
                            "value": ec["value"],
                        }
                        break

        circuit = {
            "reference": ref,
            "value": comp.get("value", ""),
            "lib_id": comp.get("lib_id", ""),
            "type": "bjt",
            "base_net": base_net,
            "collector_net": collector_net,
            "emitter_net": emitter_net,
            "collector_is_power": ctx.is_power_net(collector_net),
            "emitter_is_ground": ctx.is_ground(emitter_net),
            "load_type": load_type,
            "base_resistors": [{"reference": r["reference"], "value": r["value"]} for r in base_resistors],
            "base_driver_ics": [{"reference": ic["reference"], "value": ic["value"]} for ic in base_ics],
            "base_pulldown": base_pulldown,
            "emitter_resistor": emitter_resistor,
            "detector": "detect_transistor_circuits",
            "rule_id": "TR-DET",
            "category": "discrete_semiconductors",
            "severity": "info",
            "confidence": "deterministic",
            "evidence_source": "topology",
            "summary": f"Transistor {ref} bjt",
            "description": "BJT transistor circuit detected",
            "components": [ref],
            "nets": [],
            "pins": [],
            "recommendation": "",
            "report_context": {"section": "Discrete Semiconductors", "impact": "", "standard_ref": ""},
            "provenance": make_provenance("transistor_bjt", "deterministic", [ref]),
        }
        transistor_circuits.append(circuit)

    return transistor_circuits


def postfilter_vd_and_dedup(voltage_dividers: list[dict], feedback_networks: list[dict],
                            transistor_circuits: list[dict],
                            nets: dict | None = None) -> tuple[list[dict], list[dict]]:
    """Post-filter: remove VDs on transistor gate/base nets and deduplicate."""
    # ---- Post-filter: remove voltage dividers on transistor gate/base nets ----
    _gate_base_nets = set()
    for tc in transistor_circuits:
        if tc["type"] == "mosfet" and tc.get("gate_net"):
            _gate_base_nets.add(tc["gate_net"])
        elif tc["type"] == "bjt" and tc.get("base_net"):
            _gate_base_nets.add(tc["base_net"])

    # Also exclude VDs whose mid_net connects to an opamp inverting input
    if nets:
        for vd in voltage_dividers:
            mid = vd["mid_net"]
            if mid in nets:
                for p in nets[mid]["pins"]:
                    pname = p.get("pin_name", "").upper()
                    if any(x in pname for x in ("IN-", "INV", "INN")):
                        _gate_base_nets.add(mid)
                        break

    if _gate_base_nets:
        voltage_dividers = [
            vd for vd in voltage_dividers
            if vd["mid_net"] not in _gate_base_nets
        ]
        feedback_networks = [
            fn for fn in feedback_networks
            if fn["mid_net"] not in _gate_base_nets
        ]

    # ---- Post-filter: deduplicate voltage dividers by network topology ----
    _vd_groups: dict[tuple[str, str, str], list[dict]] = {}
    for vd in voltage_dividers:
        key = (vd["top_net"], vd["mid_net"], vd["bottom_net"])
        _vd_groups.setdefault(key, []).append(vd)
    deduped_vds = [entries[0] for entries in _vd_groups.values()]

    # Also deduplicate feedback_networks the same way
    _fn_groups: dict[tuple[str, str, str], list[dict]] = {}
    for fn in feedback_networks:
        key = (fn["top_net"], fn["mid_net"], fn["bottom_net"])
        _fn_groups.setdefault(key, []).append(fn)
    deduped_fns = [entries[0] for entries in _fn_groups.values()]

    return deduped_vds, deduped_fns


def enrich_transistor_led_drivers(ctx: AnalysisContext, transistor_circuits: list[dict]) -> None:
    """Enrich transistor circuits with LED driver info. Modifies transistor_circuits in-place.

    Mutates *transistor_circuits* in place (detector, rule_id, category, summary of
    matching records); returns None by design.
    """
    for tc in transistor_circuits:
        is_mosfet = tc.get("type") == "mosfet"
        is_bjt = tc.get("type") == "bjt"
        if not is_mosfet and not is_bjt:
            continue
        load_net = tc.get("drain_net") if is_mosfet else tc.get("collector_net")
        if not load_net:
            continue
        # Look at components on the load net for a resistor
        load_comps = ctx.nq.components_on_net(load_net, exclude_refs={tc["reference"]})
        for dc in load_comps:
            if dc["type"] != "resistor":
                continue
            # Reject resistors that are too large for current limiting,
            # or whose value field can't be parsed (e.g. "215k_0402_C0123XYZ"
            # from importers that append package/MPN suffixes). Without a
            # parseable value we can't confirm current-limiting role, so skip
            # to avoid false-positive LED driver findings.
            r_ohms = ctx.parsed_values.get(dc["reference"])
            if r_ohms is None or r_ohms > 100e3:
                continue
            # Follow the resistor to its other net
            r_n1, r_n2 = ctx.get_two_pin_nets(dc["reference"])
            other_net = r_n2 if r_n1 == load_net else r_n1
            if not other_net or other_net == load_net:
                continue
            # Check if an LED is on that net
            other_comps = ctx.nq.components_on_net(other_net, exclude_refs={dc["reference"]})
            for oc in other_comps:
                if oc["type"] == "led":
                    # Verify LED actually has a pin on other_net
                    led_n1, led_n2 = ctx.get_two_pin_nets(oc["reference"])
                    if led_n1 != other_net and led_n2 != other_net:
                        continue
                    led_comp = ctx.comp_lookup.get(oc["reference"], {})
                    # Find what power rail the LED's other pin connects to
                    led_other = led_n2 if led_n1 == other_net else led_n1
                    led_power = led_other if led_other and ctx.is_power_net(led_other) else None
                    tc["led_driver"] = {
                        "led_ref": oc["reference"],
                        "led_value": led_comp.get("value", ""),
                        "current_resistor": dc["reference"],
                        "current_resistor_value": dc.get("value", ""),
                        "power_rail": led_power,
                    }
                    ohms = ctx.parsed_values.get(dc["reference"])
                    if ohms and led_power:
                        tc["led_driver"]["resistor_ohms"] = ohms
                    # Update envelope fields on the transistor circuit dict
                    tc["detector"] = "detect_led_drivers"
                    tc["rule_id"] = "LD-DET"
                    tc["category"] = "led_control"
                    tc["severity"] = "info"
                    tc["confidence"] = "deterministic"
                    tc["evidence_source"] = "topology"
                    tc["summary"] = f"LED driver {tc['reference']}"
                    tc["description"] = f"Transistor {tc['reference']} driving LED {oc['reference']}"
                    tc["components"] = [tc["reference"], oc["reference"], dc["reference"]]
                    tc["nets"] = []
                    tc["pins"] = []
                    tc["recommendation"] = ""
                    tc["report_context"] = {"section": "LED Control", "impact": "", "standard_ref": ""}
                    tc["provenance"] = make_provenance("led_driver_transistor", "deterministic", [tc["reference"], oc["reference"], dc["reference"]])
                    break
            if "led_driver" in tc:
                break


def _is_reference_net_name(net_name: str) -> bool:
    """A reference or bias node by its own name: a token ending in REF or starting with
    VREF (VREF, 2V5_REF, AREF, DDR_VREFCA), not REFCLK or REFRIG."""
    return any(t.endswith("REF") or t.startswith("VREF")
               for t in re.findall(r"[A-Z]+|[0-9]+", net_leaf(net_name).upper()))


def _ic_supply_pin(pin: dict) -> bool:
    """A power input named as a supply (VCC, VDDA, VS, V+), not a reference input (VREF)."""
    name = re.sub(r"[^0-9A-Z+]", "", str(pin.get("pin_name") or "").upper())
    return (pin.get("pin_type") == "power_in" and "REF" not in name
            and ("VCC" in name or "VDD" in name or name in ("VS", "V+", "VIN")))


def _reference_net(ctx: AnalysisContext, net_name: str, regulator_outputs: set) -> bool:
    """A reference-named node that nothing makes a rail: no regulator, reference or other
    active output drives it and no IC takes its supply from it (a divider tap, a REF input)."""
    if not _is_reference_net_name(net_name) or net_name in regulator_outputs:
        return False
    return not any((p.get("pin_type") in ("power_out", "output")
                    and (ctx.comp_lookup.get(p.get("component")) or {}).get("type") in ("ic", "diode"))
                   or _ic_supply_pin(p)
                   for p in (ctx.nets.get(net_name) or {}).get("pins", []))


def detect_design_observations(ctx: AnalysisContext, results: dict) -> list[dict]:
    """Generate structured design observations for higher-level analysis."""
    # EQ-070: Threshold comparisons for design quality metrics
    design_observations: list[dict] = []

    # Build helper sets
    decoupled_rails = {d["rail"] for d in results.get("decoupling_analysis", [])}
    connector_nets = set()
    for net_name, net_info in ctx.nets.items():
        for p in net_info["pins"]:
            comp = ctx.comp_lookup.get(p["component"])
            if comp and comp["type"] in ("connector", "test_point"):
                connector_nets.add(net_name)
    protected_nets = {n for p in results.get("protection_devices", [])
                      for n in (p.get("protected_nets") or [p["protected_net"]])}

    # Deduplicate multi-unit ICs (same ref, different units)
    unique_ics = get_unique_ics(ctx)

    # 1. IC power pin decoupling status (a reference node nothing drives is not a rail)
    regulator_outputs = {r.get("output_rail") for r in results.get("power_regulators", [])}
    for ic in unique_ics:
        ref = ic["reference"]
        ic_power_nets = {net for net, _ in ctx.ref_pins.get(ref, {}).values()
                         if net and ctx.is_power_net(net) and not ctx.is_ground(net)
                         and not _reference_net(ctx, net, regulator_outputs)}
        undecoupled = sorted([r for r in ic_power_nets if r not in decoupled_rails])
        if undecoupled:
            design_observations.append({
                "category": "decoupling",
                "component": ref,
                "value": ic["value"],
                "rails_without_caps": undecoupled,
                "rails_with_caps": sorted([r for r in ic_power_nets if r in decoupled_rails]),
                "detector": "detect_design_observations",
                "rule_id": "DO-DET",
                "severity": "info",
                "confidence": "heuristic",
                "evidence_source": "topology",
                "summary": f"IC {ref} missing decoupling on {', '.join(undecoupled)}",
                "description": "IC power pin(s) without decoupling capacitors",
                "components": [ref],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("obs_topology", "heuristic", [ref]),
            })

    # 2. Regulator capacitor status
    for reg in results.get("power_regulators", []):
        in_rail = reg.get("input_rail")
        out_rail = reg.get("output_rail")
        missing = {}
        if in_rail and in_rail not in decoupled_rails:
            missing["input"] = in_rail
        # The decoupling detector reads a VSS-named supply as ground and counts none of its
        # capacitors, so it is never reported as missing them.
        if out_rail and out_rail not in decoupled_rails and out_rail not in ctx.vss_supply_rails:
            missing["output"] = out_rail
        if missing:
            design_observations.append({
                "category": "regulator_caps",
                "component": reg["ref"],
                "value": reg["value"],
                "topology": reg.get("topology"),
                "missing_caps": missing,
                "detector": "detect_design_observations",
                "rule_id": "DO-DET",
                "severity": "info",
                "confidence": "heuristic",
                "evidence_source": "topology",
                "summary": f"Regulator {reg['ref']} missing capacitors",
                "description": "Regulator missing input or output capacitors",
                "components": [reg["ref"]],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("obs_topology", "heuristic", [reg["ref"]]),
            })

    # 3. Single-pin signal nets
    # A port pin placed under an alternate (I2C3_SCL on PA8) is still a port pin.
    base_pin_names = {(c["reference"], cp["number"]): cp["base_name"]
                      for c in ctx.components for cp in c.get("pins", []) if "base_name" in cp}
    single_pin_nets = []
    for net_name, net_info in ctx.nets.items():
        if net_name.startswith("__unnamed_"):
            continue
        if net_info.get("no_connect"):
            continue
        if ctx.is_power_net(net_name) or ctx.is_ground(net_name):
            continue
        if net_name in connector_nets:
            continue
        real_pins = [p for p in net_info["pins"] if not p["component"].startswith("#")]
        if len(real_pins) == 1:
            p = real_pins[0]
            comp = ctx.comp_lookup.get(p["component"])
            if comp and comp["type"] == "ic":
                pin_name = p.get("pin_name", p["pin_number"])
                base_name = base_pin_names.get((p["component"], p["pin_number"]))
                if any(re.match(r'^P[A-K]\d', n.upper()) or re.match(r'^GPIO', n.upper())
                       for n in (pin_name, base_name) if n):
                    continue
                single_pin_nets.append({
                    "component": p["component"],
                    "pin": pin_name,
                    "net": net_name,
                })
    if single_pin_nets:
        design_observations.append({
            "category": "single_pin_nets",
            "count": len(single_pin_nets),
            "nets": single_pin_nets,
            "detector": "detect_design_observations",
            "rule_id": "DO-DET",
            "severity": "info",
            "confidence": "heuristic",
            "evidence_source": "topology",
            "summary": f"Single-pin nets ({len(single_pin_nets)} nets)",
            "description": "Signal nets connected to only one pin",
            "components": [n["component"] for n in single_pin_nets],
            "nets": [],
            "pins": [],
            "recommendation": "",
            "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
            "provenance": make_provenance("obs_topology", "heuristic", [n["component"] for n in single_pin_nets]),
        })

    # 4. I2C bus pull-up status
    for net_name, net_info in ctx.nets.items():
        nn = net_name.upper()
        if "I2S" in nn:
            continue
        # Exclude I2S audio pins (SDAT, LRCK, BCLK, WSEL)
        if any(kw in nn for kw in ("SDAT", "LRCK", "BCLK", "WSEL")):
            continue
        # Exclude SPI nets — sensors with dual-function SDA/SCL pin names
        if "SPI" in nn or "MOSI" in nn or "MISO" in nn:
            continue
        # Tighten SDA regex to exclude SDAT (I2S serial data)
        is_sda = bool(re.search(r'\bSDA\b(?!T)', nn) or re.search(r'I2C.*SDA|SDA.*I2C', nn))
        is_scl = bool(re.search(r'\bSCL\b', nn) or re.search(r'I2C.*SCL|SCL.*I2C', nn))
        if "SCLK" in nn or "SCK" in nn:
            is_scl = False
        if not (is_sda or is_scl):
            continue
        line = "SDA" if is_sda else "SCL"
        has_pullup = False
        pullup_ref = None
        pullup_to = None
        for p in net_info["pins"]:
            comp = ctx.comp_lookup.get(p["component"])
            if comp and comp["type"] == "resistor":
                r_n1, r_n2 = ctx.get_two_pin_nets(p["component"])
                other = r_n2 if r_n1 == net_name else r_n1
                if other and ctx.is_power_net(other):
                    has_pullup = True
                    pullup_ref = p["component"]
                    pullup_to = other
                    break
        ic_refs = [p["component"] for p in net_info["pins"]
                   if ctx.comp_lookup.get(p["component"], {}).get("type") == "ic"]
        if ic_refs:
            design_observations.append({
                "category": "i2c_bus",
                "net": net_name,
                "line": line,
                "devices": ic_refs,
                "has_pullup": has_pullup,
                "pullup_resistor": pullup_ref,
                "pullup_rail": pullup_to,
                "detector": "detect_design_observations",
                "rule_id": "DO-DET",
                "severity": "info",
                "confidence": "heuristic",
                "evidence_source": "topology",
                "summary": f"I2C {line} bus on {net_name}",
                "description": f"I2C {line} bus detected with {len(ic_refs)} device(s)",
                "components": ic_refs,
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("obs_topology", "heuristic", ic_refs),
            })

    # 5. Reset pin configuration
    for ic in unique_ics:
        ref = ic["reference"]
        for pnum, (net, _) in ctx.ref_pins.get(ref, {}).items():
            if not net or net.startswith("__unnamed_") or (net in ctx.nets and ctx.nets[net].get("no_connect")):
                continue
            pin_name = ""
            if net in ctx.nets:
                for p in ctx.nets[net]["pins"]:
                    if p["component"] == ref and p["pin_number"] == pnum:
                        pin_name = p.get("pin_name", "").upper()
                        break
            if pin_name not in ("NRST", "~{RESET}", "RESET", "~{RST}", "RST", "~{NRST}", "MCLR", "~{MCLR}"):
                continue
            has_resistor = False
            has_capacitor = False
            connected_to = []
            if net in ctx.nets:
                for p in ctx.nets[net]["pins"]:
                    comp = ctx.comp_lookup.get(p["component"])
                    if not comp or p["component"] == ref:
                        continue
                    if comp["type"] == "resistor":
                        has_resistor = True
                    elif comp["type"] == "capacitor":
                        has_capacitor = True
                    connected_to.append({"ref": p["component"], "type": comp["type"]})
            design_observations.append({
                "category": "reset_pin",
                "component": ref,
                "value": ic["value"],
                "pin": pin_name,
                "net": net,
                "has_pullup": has_resistor,
                "has_filter_cap": has_capacitor,
                "connected_components": connected_to,
                "detector": "detect_design_observations",
                "rule_id": "DO-DET",
                "severity": "info",
                "confidence": "heuristic",
                "evidence_source": "topology",
                "summary": f"Reset pin on {ref} ({pin_name})",
                "description": f"Reset pin configuration for {ref}",
                "components": [ref],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("obs_topology", "heuristic", [ref]),
            })

    # 6. Regulator feedback voltage estimation
    for reg in results.get("power_regulators", []):
        if "estimated_vout" in reg:
            obs = {
                "category": "regulator_voltage",
                "component": reg["ref"],
                "value": reg["value"],
                "topology": reg.get("topology"),
                "estimated_vout": reg["estimated_vout"],
                "assumed_vref": reg.get("assumed_vref"),
                "vref_source": reg.get("vref_source", "heuristic"),
                "feedback_divider": reg.get("feedback_divider"),
                "input_rail": reg.get("input_rail"),
                "output_rail": reg.get("output_rail"),
            }
            out_rail = reg.get("output_rail", "")
            rail_v = _parse_voltage_from_net_name(out_rail)
            if rail_v and reg["estimated_vout"] > 0:
                # A negative rail is estimated as a magnitude here (inverting
                # regulators are not always recognised), so compare |Vout| to |Vrail|.
                pct_diff = abs(reg["estimated_vout"] - abs(rail_v)) / abs(rail_v)
                if pct_diff > 0.15:
                    obs["vout_net_mismatch"] = {
                        "net_name": out_rail,
                        "net_voltage": rail_v,
                        "estimated_vout": reg["estimated_vout"],
                        "percent_diff": round(pct_diff * 100, 1),
                    }
            obs["detector"] = "detect_design_observations"
            obs["rule_id"] = "DO-DET"
            obs["severity"] = "info"
            obs["confidence"] = "heuristic"
            obs["evidence_source"] = "topology"
            obs["summary"] = f"Regulator {reg['ref']} estimated Vout={reg['estimated_vout']}V"
            obs["description"] = "Regulator output voltage estimated from feedback divider"
            obs["components"] = [reg["ref"]]
            obs["nets"] = []
            obs["pins"] = []
            obs["recommendation"] = ""
            obs["report_context"] = {"section": "Design Observations", "impact": "", "standard_ref": ""}
            obs["provenance"] = make_provenance("obs_topology", "heuristic", [reg["ref"]])
            design_observations.append(obs)

    # 7. Switching regulator bootstrap status
    for reg in results.get("power_regulators", []):
        if reg.get("topology") == "switching" and reg.get("inductor"):
            design_observations.append({
                "category": "switching_regulator",
                "component": reg["ref"],
                "value": reg["value"],
                "inductor": reg.get("inductor"),
                "has_bootstrap": reg.get("has_bootstrap", False),
                "input_rail": reg.get("input_rail"),
                "output_rail": reg.get("output_rail"),
                "detector": "detect_design_observations",
                "rule_id": "DO-DET",
                "severity": "info",
                "confidence": "heuristic",
                "evidence_source": "topology",
                "summary": f"Switching regulator {reg['ref']}",
                "description": f"Switching regulator with inductor {reg.get('inductor')}",
                "components": [reg["ref"]],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("obs_topology", "heuristic", [reg["ref"]]),
            })

    # 8. USB data line protection status
    for net_name in ctx.nets:
        nn = net_name.upper()
        is_usb = any(x in nn for x in ("USB_D", "USBDP", "USBDM", "USB_DP", "USB_DM"))
        if not is_usb and nn in ("D+", "D-", "DP", "DM"):
            if net_name in ctx.nets:
                for p in ctx.nets[net_name]["pins"]:
                    comp = ctx.comp_lookup.get(p["component"])
                    if comp:
                        cv = (comp.get("value", "") + " " + comp.get("lib_id", "")).upper()
                        if "USB" in cv:
                            is_usb = True
                            break
        if is_usb:
            _usb_devices = [p["component"] for p in ctx.nets[net_name]["pins"]
                            if not ctx.comp_lookup.get(p["component"], {}).get("type") in (None,)]
            design_observations.append({
                "category": "usb_data",
                "net": net_name,
                "has_esd_protection": net_name in protected_nets,
                "devices": _usb_devices,
                "detector": "detect_design_observations",
                "rule_id": "DO-DET",
                "severity": "info",
                "confidence": "heuristic",
                "evidence_source": "topology",
                "summary": f"USB data line {net_name}",
                "description": f"USB data net {net_name} detected",
                "components": _usb_devices,
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("obs_topology", "heuristic", _usb_devices),
            })

    # 9. Crystal load capacitance
    for xtal in results.get("crystal_circuits", []):
        if "effective_load_pF" in xtal:
            design_observations.append({
                "category": "crystal",
                "component": xtal["reference"],
                "value": xtal.get("value"),
                "effective_load_pF": xtal["effective_load_pF"],
                "load_caps": xtal.get("load_caps", []),
                "in_typical_range": 4 <= xtal["effective_load_pF"] <= 30,
                "detector": "detect_design_observations",
                "rule_id": "DO-DET",
                "severity": "info",
                "confidence": "heuristic",
                "evidence_source": "topology",
                "summary": f"Crystal load cap {xtal['reference']} = {xtal['effective_load_pF']}pF",
                "description": "Crystal load capacitance observation",
                "components": [xtal["reference"]],
                "nets": [],
                "pins": [],
                "recommendation": "",
                "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
                "provenance": make_provenance("obs_topology", "heuristic", [xtal["reference"]]),
            })

    # 10. Decoupling frequency coverage per rail
    for decoup in results.get("decoupling_analysis", []):
        caps = decoup.get("capacitors", [])
        farads_list = [c.get("farads", 0) for c in caps]
        has_bulk = any(f >= 1e-6 for f in farads_list)
        has_bypass = any(10e-9 <= f <= 1e-6 for f in farads_list)
        has_hf = any(f < 10e-9 for f in farads_list)
        design_observations.append({
            "category": "decoupling_coverage",
            "rail": decoup["rail"],
            "cap_count": len(caps),
            "total_uF": decoup.get("total_capacitance_uF"),
            "has_bulk": has_bulk,
            "has_bypass": has_bypass,
            "has_high_freq": has_hf,
            "detector": "detect_design_observations",
            "rule_id": "DO-DET",
            "severity": "info",
            "confidence": "heuristic",
            "evidence_source": "topology",
            "summary": f"Decoupling coverage on {decoup['rail']}",
            "description": f"Decoupling frequency coverage for rail {decoup['rail']}",
            "components": [c["ref"] for c in caps],
            "nets": [],
            "pins": [],
            "recommendation": "",
            "report_context": {"section": "Design Observations", "impact": "", "standard_ref": ""},
            "provenance": make_provenance("obs_topology", "heuristic", [c["ref"] for c in caps]),
        })

    return design_observations


# ---------------------------------------------------------------------------
# Solder Jumper Inventory (SJ-DET)
# ---------------------------------------------------------------------------

def detect_shorted_two_pin_components(ctx: AnalysisContext) -> list[dict]:
    """SP-001: Report two-pin components with both pins on the same net.

    A resistor, capacitor, inductor or diode whose two pins land on one net
    does nothing. It is almost always a wiring mistake, and the mistake is
    invisible to ERC and DRC: the board is internally consistent, every pin is
    connected, and the netlist is legal. Only the intent is wrong.

    This condition was already being computed and thrown away.
    ``index_two_pin_components()`` (detector_helpers.py) skips these parts so
    downstream detectors do not divide by a degenerate topology, which is
    correct for those detectors but meant a shorted part vanished from the
    analysis instead of being reported. It is dropped from divider, RC,
    pull-up and termination analysis at every call site, and nothing tells the
    user why.

    Deliberate shorts are excluded rather than reported: jumpers and net ties
    exist to bridge a net, DNP parts are not fitted, and a zero-ohm link with
    both ends on one net is a net tie by another name.

    Parts with more than two pins are excluded too. ``get_two_pin_nets()``
    reads pins "1" and "2" without checking the pin count, so without a guard
    this fires on rheostat-wired potentiometers, dual-anode diode symbols, ESD
    arrays, passive packs and misclassified connectors. Unannotated references
    ("R?") are skipped because they collide with each other in the pin-net map,
    and findings are deduplicated by reference so a hierarchical sheet
    instanced n times reports once rather than n times.

    Five or more hits on one net collapse into one net-level finding (same
    rule_id, confidence ``heuristic``): on the corpus that pattern is almost
    always the net map having merged two rails, not N real shorts.

    Severity is ``warning`` rather than ``error`` deliberately. A netlist-
    building bug that over-unions two nets would surface here as a false
    positive, so the finding should prompt a look rather than block a build
    until its false-positive rate is measured across the corpus.
    """
    findings: list[dict] = []

    # Types where one net across both pins is never useful. Jumpers and net
    # ties are absent by design -- bridging is what they are for. The type
    # strings must match what classify_component() emits: it produces
    # "ferrite_bead", never bare "ferrite", so the latter silently matched
    # nothing.
    SHORTABLE = ("resistor", "capacitor", "inductor", "ferrite_bead", "diode")
    # Five or more hits on one net collapse into a single net-level finding
    # (see the end of this function).
    MASS_SHORT_THRESHOLD = 5

    # One finding per reference. A hierarchical sheet instanced more than once
    # puts the same reference in ctx.components once per instance, which would
    # otherwise emit a duplicate finding per instance.
    seen: set[str] = set()

    for comp in ctx.components:
        if comp.get("type") not in SHORTABLE:
            continue
        if comp.get("dnp"):
            continue

        ref = comp.get("reference")
        if not ref:
            continue

        # Unannotated parts share a reference ("R?", "D?"), so they collide in
        # the pin-net map and report each other's nets. Nothing useful can be
        # said about them until the schematic is annotated.
        if "?" in ref:
            continue

        # get_two_pin_nets() reads pins "1" and "2" without checking that the
        # part only HAS two pins, so any multi-pin component whose first two
        # pins share a net would fire: pots wired as rheostats (wiper tied to
        # one end), dual-anode Schottky symbols, ESD arrays, resistor and
        # capacitor packs, and connectors that the reference prefix
        # misclassifies as a passive.
        if len(ctx.ref_pins.get(ref, {})) != 2:
            continue

        n1, n2 = ctx.get_two_pin_nets(ref)
        if not n1 or not n2 or n1 != n2:
            continue

        lib_id = (comp.get("lib_id") or "").lower()
        if "nettie" in lib_id or "net_tie" in lib_id or "jumper" in lib_id:
            continue

        # A 0R link shorted to one net is a net tie spelled differently.
        parsed = ctx.parsed_values.get(ref)
        if comp.get("type") == "resistor" and parsed == 0:
            continue

        if ref in seen:
            continue
        seen.add(ref)

        value = comp.get("value") or "?"
        findings.append(make_finding(
            detector=Det.SHORTED_TWO_PIN,
            rule_id="SP-001",
            category="signal",
            severity="warning",
            confidence="deterministic",
            evidence_source="topology",
            summary=(f"{ref} ({value}) has both pins on net '{n1}' -- the "
                     f"component is shorted out and has no effect"),
            description=(
                f"{ref} is a {comp.get('type')} with pin 1 and pin 2 both "
                f"connected to '{n1}'. Current bypasses the part entirely, so "
                f"it contributes nothing to the circuit. ERC and DRC pass on "
                f"this: every pin is connected and the netlist is internally "
                f"consistent, so only intent distinguishes it from a "
                f"deliberate link. Jumpers, net ties, zero-ohm links and DNP "
                f"parts are excluded from this check."),
            components=[ref],
            nets=[n1],
            recommendation=(
                f"Confirm {ref} is meant to bridge '{n1}'. If not, one pin is "
                f"on the wrong net -- check which node it should reach."),
            net=n1,
            component_type=comp.get("type"),
            value=value,
            schema_era="v3.0",
        ))

    # Collapse mass hits per net. When the net map has merged two rails
    # (an analyzer connectivity defect) every decoupling cap
    # on the merged net reads as "shorted": the kicad-cli oracle refuted 205
    # of 243 corpus findings for exactly that reason, essentially all on nets
    # with five or more hits, while genuine shorts come one to four per net.
    # One net-level finding keeps the signal (a tripwire for the net map, or a
    # genuinely unfinished schematic) without N misleading per-part warnings.
    by_net: dict[str, list[dict]] = {}
    for f in findings:
        by_net.setdefault(f["net"], []).append(f)
    collapsed: list[dict] = []
    for net, group in by_net.items():
        if len(group) < MASS_SHORT_THRESHOLD:
            collapsed.extend(group)
            continue
        refs = [f["components"][0] for f in group]
        collapsed.append(make_finding(
            detector=Det.SHORTED_TWO_PIN,
            rule_id="SP-001",
            category="signal",
            severity="warning",
            confidence="heuristic",
            evidence_source="topology",
            summary=(f"{len(group)} two-pin components have both pins on net "
                     f"'{net}' ({refs[0]} .. {refs[-1]}) -- mass short or "
                     f"net-map problem"),
            description=(
                f"{len(group)} two-pin parts ({', '.join(refs)}) each have pin "
                f"1 and pin 2 on '{net}'. Either the schematic is unfinished "
                f"(parts placed but not yet wired to their second node) or "
                f"the extracted net map has merged two rails -- typically a "
                f"power rail and ground -- so every decoupling capacitor "
                f"between them reads as shorted. In the second case the "
                f"other net-based findings on this net are suspect too."),
            components=refs,
            nets=[net],
            recommendation=(
                f"Check '{net}' in KiCad first: if it carries both a supply "
                f"and ground, or far more pins than expected, the net map is "
                f"wrong and the parts are fine (report the board). Otherwise "
                f"wire each listed part to its second node."),
            net=net,
            component_count=len(group),
            schema_era="v3.0",
        ))

    return collapsed


def detect_solder_jumpers(ctx: AnalysisContext) -> list[dict]:
    """Enumerate every solder jumper in the design and report its default state.

    Emits one INFO finding per jumper so downstream rules and LLM reviewers
    can tell at a glance whether a net is bridged-by-default (works without
    any user action) or open-by-default (requires soldering to function).
    KiCad encodes this in the library symbol and footprint name — e.g.
    ``Jumper:SolderJumper_2_Bridged`` with footprint
    ``SolderJumper-2_P1.3mm_Bridged_*`` is closed until the bridge is
    scored, while ``Jumper:Jumper_2_Open`` with ``*_Open_*`` is a pair of
    pads that must be soldered.

    The finding records the two nets the jumper straddles and which of
    them (if any) look like power rails by name. Rule ID ``SJ-DET``.
    """
    findings: list[dict] = []
    nets = ctx.nets or {}

    # Build ref → [(pin_number, net_name)] map from the nets side so we
    # handle implicit power-symbol nets (+3.3V, GND) the same as ordinary
    # wired nets.
    ref_pins: dict[str, list[tuple[str, str]]] = {}
    for net_name, net_info in nets.items():
        if not isinstance(net_info, dict):
            continue
        for pin in net_info.get("pins", []) or []:
            ref = pin.get("component") or pin.get("ref")
            pnum = pin.get("pin_number") or pin.get("pin") or ""
            if ref:
                ref_pins.setdefault(ref, []).append((str(pnum), net_name))

    for comp in ctx.components:
        if comp.get("type") != "jumper" and comp.get("category") != "jumper":
            continue
        ref = comp.get("reference")
        if not ref:
            continue
        value = comp.get("value", "") or ""
        lib_id = comp.get("lib_id", "") or ""
        footprint = comp.get("footprint", "") or ""
        state = classify_jumper_default_state(value, lib_id, footprint)

        # A 2-pin jumper is the common case; 3-pin selector jumpers exist
        # but carry multiple bridge variants (Bridged12, Bridged23). We
        # report them but don't attempt per-pin state inference here.
        pins = sorted(set(ref_pins.get(ref, [])))
        net_list = []
        for pnum, net in pins:
            if net and net not in net_list:
                net_list.append(net)

        power_nets = [n for n in net_list if is_power_net_name(n, None) and n not in ctx.pin_guarded_signals]
        ground_nets = [n for n in net_list if ctx.is_ground(n)]

        if state == "bridged":
            severity = "info"
            if len(net_list) >= 2:
                summary = (f"{ref} ({value or lib_id}) — closed by default, "
                           f"connecting {' ↔ '.join(net_list[:2])}")
            else:
                summary = f"{ref} ({value or lib_id}) — closed by default"
            recommendation = ("Bridged solder jumper conducts without user "
                              "action. Scoring/cutting the bridge isolates "
                              "the two nets. Treat as a normal connection "
                              "unless the design-intent note says otherwise.")
            impact = "Connection is live out of the box; no user action required."
        elif state == "open":
            severity = "warning" if power_nets or ground_nets else "info"
            summary = (f"{ref} ({value or lib_id}) — open by default"
                       + (f", between {' ↔ '.join(net_list[:2])}" if len(net_list) >= 2 else ""))
            recommendation = ("Open solder jumper is non-conducting until "
                              "the pads are soldered. If either side is a "
                              "power rail or required signal, the board "
                              "won't function without the solder step.")
            impact = ("Connection requires soldering; board won't pass "
                      "bring-up if left unpopulated."
                      if power_nets or ground_nets else
                      "Optional / configuration jumper.")
        elif state == "switchable":
            severity = "info"
            summary = (f"{ref} ({value or lib_id}) — physical shunt (state "
                       "set at assembly/board-bring-up)")
            recommendation = ("Shunt-block configuration — actual conduction "
                              "depends on whether the shunt is installed.")
            impact = "Runtime-configurable; state not visible in schematic."
        else:
            severity = "info"
            summary = (f"{ref} ({value or lib_id}) — jumper with unknown "
                       "default state")
            recommendation = ("Unable to determine default conduction from "
                              "symbol/footprint. Inspect manually.")
            impact = ""

        findings.append({
            "detector": "detect_solder_jumpers",
            "rule_id": "SJ-DET",
            "severity": severity,
            "confidence": "deterministic",
            "evidence_source": "symbol_footprint",
            "category": "topology",
            "summary": summary,
            "reference": ref,
            "value": value,
            "lib_id": lib_id,
            "footprint": footprint,
            "default_state": state,
            "nets": net_list,
            "power_nets": power_nets,
            "ground_nets": ground_nets,
            "pin_count": len(pins),
            "components": [ref],
            "pins": [f"{ref}.{pn}" for pn, _ in pins],
            "recommendation": recommendation,
            "report_context": {
                "section": "Solder Jumpers",
                "impact": impact,
                "standard_ref": "",
            },
            "provenance": make_provenance("sj_symbol_footprint", "deterministic", [ref]),
        })

    return findings


# ---------------------------------------------------------------------------
# Rail source audit (RS-001 / RS-002)
# ---------------------------------------------------------------------------

_SWITCH_INPUT_PINS = frozenset({"VIN", "IN", "INPUT", "VI"})
_SWITCH_OUTPUT_PINS = frozenset({"VOUT", "OUT", "OUTPUT", "VO"})


def audit_rail_sources(ctx: AnalysisContext,
                       power_regulators: list[dict] | None = None,
                       solder_jumpers: list[dict] | None = None,
                       bridge_facts=None) -> list[dict]:
    """Audit every power-classified net for a declared source.

    A rail with no `power_out` pin, no `PWR_FLAG` / `#FLG`, and no
    regulator output mapping is source-less on paper. The solder-jumper
    aware trace: a bridged-by-default jumper joins two nets electrically;
    if the other side has a source, the audited rail is sourced via the
    jumper (INFO). A rail reached only through an *open* jumper is an
    error — the board won't power up until the user closes the jumper.

    Rule tiers:
      RS-001  rail has no source path at all                    severity=warning
      RS-002  only source path is through an open jumper        severity=error
              (board needs a solder action to function)
      info    sourced directly OR via a bridged jumper         (recorded for audit)
    """
    findings: list[dict] = []
    nets = ctx.nets or {}

    # Regulator output nets (from the regulator detector) are sources
    # even when the regulator symbol uses power_in on its OUT pin.
    reg_output_nets: set[str] = set()
    for reg in (power_regulators or []):
        out = reg.get("output_rail") or reg.get("vout_net")
        if out:
            reg_output_nets.add(out)

    # Build a quick map of net → list of (neighbour, state, jumper_ref) tuples
    # for solder jumpers that straddle the net.
    if bridge_facts is None:
        bridge_facts = build_bridge_facts(
            ctx.components or [], build_ref_pins(nets), solder_jumpers)
    jumper_bridges: dict[str, list[tuple[str, str, str]]] = {}
    for fact in bridge_facts.jumpers:
        state = fact.default_state
        nets_straddled = fact.nets
        # Only 2-net jumpers (standard SolderJumper_2_Bridged / _Open) are
        # amenable to one-hop traversal. 3-pin selector jumpers (e.g.
        # SolderJumper_3_Bridged12 / _Bridged23) encode the actual shorted
        # pair in the footprint suffix — picking any two of the three nets
        # would misidentify which are bridged. Skip until per-pin state
        # resolution is available.
        if len(nets_straddled) != 2 or state not in ("bridged", "open"):
            continue
        a, b = nets_straddled[0], nets_straddled[1]
        jumper_bridges.setdefault(a, []).append((b, state, fact.ref))
        jumper_bridges.setdefault(b, []).append((a, state, fact.ref))

    # A net tie joins its nets into one conductor: a rail tied to a sourced net is sourced.
    ties = tie_conductors(bridge_facts)

    def _has_direct_source(net_info: dict, net_name: str) -> bool:
        # Direct power_out pin anywhere on the net, OR an explicit PWR_FLAG
        # tied to it, OR the rail is a regulator output.
        # NOTE: #PWR symbols are KiCad power port instances; they appear as
        # power_in in the analyzer and are NOT treated as sources here.
        if net_info.get("has_pwr_flag"):
            return True
        for p in net_info.get("pins", []):
            if p.get("pin_type") == "power_out":
                return True
            comp = p.get("component") or ""
            if comp.startswith("#FLG"):
                return True
        return net_name in reg_output_nets or net_name in switch_output_nets

    # A load or USB power switch passes its input rail on: its output net is
    # sourced when its input conductor is. Chains of switches settle in a few passes.
    switch_pins: list[tuple[str, str]] = []  # (input net, output net)
    switch_refs = {c["reference"] for c in ctx.components
                   if c.get("type") == "ic"
                   and any(k in (c.get("lib_id", "") + " " + c.get("value", "")).lower()
                           for k in LOAD_SWITCH_KEYWORDS)}
    if switch_refs:
        # (net, channel): a dual switch numbers its channels (VIN1 -> VOUT1, VIN2 -> VOUT2);
        # an unnumbered side pairs with every channel.
        by_ref: dict[str, dict[str, set[tuple[str, str]]]] = {}
        for net_name, net_info in nets.items():
            for p in net_info.get("pins", []):
                if p.get("component") in switch_refs:
                    name = (p.get("pin_name") or "").upper()
                    base = name.rstrip("0123456789_")
                    channel = name[len(base):].lstrip("_")
                    side = ("in" if base in _SWITCH_INPUT_PINS
                            else "out" if base in _SWITCH_OUTPUT_PINS else None)
                    if side:
                        by_ref.setdefault(p["component"], {"in": set(), "out": set()})[side].add(
                            (net_name, channel))
        for sides in by_ref.values():
            switch_pins += sorted({(i, o) for i, ci in sides["in"] for o, co in sides["out"]
                                   if not (ci and co and ci != co)})
    switch_output_nets: set[str] = set()

    def _input_sourced(in_net: str) -> bool:
        # The switch input is sourced directly, through a net tie, or across a
        # bridged-by-default jumper (RS-003 territory: functional out of the box).
        conductor = conductor_of(ties, in_net)
        if any(_has_direct_source(nets.get(n, {}), n) for n in conductor):
            return True
        return any(state == "bridged"
                   and any(_has_direct_source(nets.get(m, {}), m) for m in conductor_of(ties, nb))
                   for n in conductor for nb, state, _ in jumper_bridges.get(n, []))

    for _ in range(len(switch_pins)):
        grew = False
        for in_net, out_net in switch_pins:
            if out_net not in switch_output_nets and _input_sourced(in_net):
                switch_output_nets.add(out_net)
                grew = True
        if not grew:
            break

    def _power_rail(net_name: str, net_info: dict) -> bool:
        # "Power rail" = named like a rail OR has a power_in pin on it that is
        # not a bootstrap pin (a BST net is fed by its capacitor, never a source).
        # A reference node (VREF, 2V5_REF) is a rail only when an output drives it, and
        # then it is sourced: either way it has nothing to report, unless an IC takes
        # its supply from it.
        if net_name.startswith("__unnamed_") or (
                _is_reference_net_name(net_name)
                and not any(_ic_supply_pin(p) for p in net_info.get("pins", []))):
            return False
        if is_power_net_name(net_name, None) and net_name not in ctx.pin_guarded_signals:
            return True
        return any(p.get("pin_type") == "power_in"
                   and not _is_bootstrap_pin_name(p.get("pin_name") or "")
                   for p in net_info.get("pins", []))

    for net_name, net_info in nets.items():
        if not _power_rail(net_name, net_info):
            continue
        if ctx.is_ground(net_name):
            continue  # ground handled elsewhere
        conductor = conductor_of(ties, net_name)
        if any(_has_direct_source(nets.get(n, {}), n) for n in conductor):
            continue  # sourced directly or through a net tie, nothing to report

        # No direct source. Trace one hop through jumpers.
        jumper_paths = [j for n in conductor for j in jumper_bridges.get(n, [])]
        bridged_sources: list[tuple[str, str]] = []   # (neighbour, jumper_ref)
        open_sources: list[tuple[str, str]] = []
        for neighbour, state, jref in jumper_paths:
            neighbour_info = nets.get(neighbour, {})
            if not neighbour_info:
                continue
            if any(_has_direct_source(nets.get(n, {}), n) for n in conductor_of(ties, neighbour)):
                if state == "bridged":
                    bridged_sources.append((neighbour, jref))
                else:  # open
                    open_sources.append((neighbour, jref))

        if bridged_sources:
            # Rail has an upstream source via a closed-by-default jumper.
            # That's functional out of the box; record it as info.
            # RS-001 is reserved for "no source at all" (warning). Sourcing
            # via a bridged jumper gets its own rule_id RS-003 (info) so
            # reviewers and CI gates can filter the two cases independently.
            # Only solder jumpers reach this branch; ferrite beads are not
            # traced here.
            neighbours = ", ".join(f"{n} via {j}" for n, j in bridged_sources)
            findings.append({
                "detector": "audit_rail_sources",
                "rule_id": "RS-003",
                "severity": "info",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "category": "power",
                "summary": (f"{net_name} sourced via bridged solder jumper "
                            f"({neighbours})"),
                "description": (f"Net {net_name} has no direct power_out "
                                f"pin or PWR_FLAG, but reaches a sourced "
                                f"net through a bridged-by-default solder "
                                f"jumper. Functional out of the box; "
                                f"consider adding a PWR_FLAG so the rail "
                                f"is explicit in the schematic."),
                "components": [j for _, j in bridged_sources],
                "nets": [net_name] + [n for n, _ in bridged_sources],
                "pins": [],
                "source_path": "bridged_jumper",
                "bridged_neighbours": [n for n, _ in bridged_sources],
                "recommendation": (
                    "Optional: add a PWR_FLAG on this rail to declare it "
                    "explicitly. No functional change required — the "
                    "bridged jumper already provides the source."),
                "report_context": {
                    "section": "Power — Rail Sources",
                    "impact": ("Rail functions without user action; "
                               "dependent on bridged jumper."),
                    "standard_ref": "",
                },
                "provenance": make_provenance("rs_rail_audit", "deterministic", [j for _, j in bridged_sources]),
            })
            continue

        if open_sources:
            neighbours = ", ".join(f"{n} via {j}" for n, j in open_sources)
            findings.append({
                "detector": "audit_rail_sources",
                "rule_id": "RS-002",
                "severity": "error",
                "confidence": "deterministic",
                "evidence_source": "topology",
                "category": "power",
                "summary": (f"{net_name} has no source unless user solders "
                            f"a jumper ({neighbours})"),
                "description": (f"Net {net_name} has no power_out pin and "
                                f"no PWR_FLAG; the only potential source "
                                f"lies across an OPEN-by-default solder "
                                f"jumper. Board will not power up on this "
                                f"rail until the user solders the jumper "
                                f"pads."),
                "components": [j for _, j in open_sources],
                "nets": [net_name] + [n for n, _ in open_sources],
                "pins": [],
                "source_path": "open_jumper",
                "open_neighbours": [n for n, _ in open_sources],
                "recommendation": (
                    "Confirm that leaving this jumper open is the intended "
                    "factory-default. If the rail should be live out of "
                    "the box, swap the jumper symbol/footprint to a "
                    "bridged variant or add a direct connection."),
                "report_context": {
                    "section": "Power — Rail Sources",
                    "impact": ("Board will not function on this rail until "
                               "user closes the solder jumper."),
                    "standard_ref": "",
                },
                "provenance": make_provenance("rs_rail_audit", "deterministic", [j for _, j in open_sources]),
            })
            continue

        # No source at all — direct or through any jumper.
        power_in_pins = [p.get("component", "") + "." + p.get("pin_number", "")
                         for p in net_info.get("pins", [])
                         if p.get("pin_type") == "power_in"]
        # A bootstrap pin on a real part is power_in but is fed by its own
        # capacitor, not the rail; a power symbol named for the net is not one.
        if any(p.get("pin_type") == "power_in"
               and (p.get("component", "").startswith("#")
                    or not _is_bootstrap_pin_name(p.get("pin_name") or ""))
               for p in net_info.get("pins", [])):
            rs_confidence = "deterministic"
            rs_load = "carries power_in pins"
        elif power_in_pins:
            rs_confidence = "heuristic"
            rs_load = ("is named like a power rail (its only power_in pins "
                       "are bootstrap pins)")
        else:
            # Admitted by its name alone (is_power_net_name): no pin on it
            # is power_in, so whether it needs a source is a guess.
            rs_confidence = "heuristic"
            rs_load = "is named like a power rail (no power_in pin on it)"
        findings.append({
            "detector": "audit_rail_sources",
            "rule_id": "RS-001",
            "severity": "warning",
            "confidence": rs_confidence,
            "evidence_source": "topology",
            "category": "power",
            "summary": f"{net_name} has no declared source",
            "description": (f"Net {net_name} {rs_load} but has "
                            "no power_out pin, no PWR_FLAG, no regulator "
                            "output mapping, and no bridged solder jumper "
                            "path to a sourced net."),
            "components": [],
            "nets": [net_name],
            "pins": power_in_pins[:10],
            "source_path": "none",
            "recommendation": (
                "Add a PWR_FLAG to declare the rail as externally powered "
                "(e.g. from a connector) or trace the rail back to a "
                "regulator output. If the source lives on another sheet, "
                "promote the net name to a global label."),
            "report_context": {
                "section": "Power — Rail Sources",
                "impact": ("Rail has no source visible to the analyser; "
                           "likely a wiring gap or missing PWR_FLAG."),
                "standard_ref": "",
            },
            "provenance": make_provenance("rs_rail_audit", rs_confidence, []),
            "schema_era": "v3.0",
        })

    return findings


# ---------------------------------------------------------------------------
# Global label aliases (LB-001)
# ---------------------------------------------------------------------------

def detect_label_aliases(ctx: AnalysisContext) -> list[dict]:
    """Flag nets carrying two or more distinct global / hierarchical labels.

    KiCad happily lets you place both ``SLS1`` and ``RS1P`` on the same
    physical wire. The net-name resolution picks one, but the other is
    still 'real' in the sense that a human reading the schematic sees
    both — and a future refactor that renames one silently decouples
    them. Severity stays INFO because it's a maintainability risk, not
    a functional defect.

    Reads ``nets[name].labels`` populated by ``build_net_map`` — each entry
    is ``{name, type}`` where ``type`` is one of
    ``global_label / hierarchical_label / label / directive_label``.
    """
    findings: list[dict] = []
    nets = ctx.nets or {}
    for net_name, net_info in nets.items():
        applied = net_info.get("labels") or []
        # Only global and hierarchical labels cross sheets — local labels
        # are by design wire-scoped and not aliased outside their sheet.
        cross_sheet = [lbl for lbl in applied
                       if lbl.get("type") in
                           ("global_label", "hierarchical_label")]
        # A label reached through several sheet instances carries one
        # instance-qualified name per instance; the alias is the drawn name.
        names = sorted({str(lbl.get("_bare_name") or lbl.get("name", ""))
                        for lbl in cross_sheet if lbl.get("name")})
        if len(names) < 2:
            continue
        # Skip power-rail aliases: labels on GND / VCC / +3.3V / etc. are
        # almost always documentation tags for subnodes of the power net
        # (e.g. Kelvin-shunt returns labelled at the star point), not
        # namespace collisions. The LB-001 rule targets *maintainability*
        # risk — renaming a power rail label is a deliberate act, not a
        # silent decoupling. If the user genuinely needs to audit
        # power-net label entropy, a separate rule (LB-002) could be
        # added later; for now we treat this as noise.
        if ((is_power_net_name(net_name, None) and net_name not in ctx.pin_guarded_signals)
                or ctx.is_ground(net_name)):
            continue
        findings.append({
            "detector": "detect_label_aliases",
            "rule_id": "LB-001",
            "severity": "info",
            "confidence": "deterministic",
            "evidence_source": "topology",
            "category": "labels",
            "summary": (f"Net {net_name} has multiple global/hierarchical "
                        f"labels: {', '.join(names)}"),
            "description": (f"Net {net_name!r} is labelled with multiple "
                            f"names: {', '.join(names)}. KiCad treats this "
                            f"as one electrical net, but a future refactor "
                            f"that renames one label without the other "
                            f"silently decouples the two halves."),
            "components": [],
            "nets": [net_name],
            "pins": [],
            "aliases": names,
            "label_count": len(cross_sheet),
            "recommendation": (
                "Pick the canonical name and remove the other labels, OR "
                "document the alias intentionally (e.g. an expressly named "
                "test point). If this is a cross-sheet connection via both "
                "global and hierarchical labels, prefer one or the other "
                "style consistently."),
            "report_context": {
                "section": "Labels",
                "impact": "Maintainability — silent alias across future edits.",
                "standard_ref": "",
            },
            "provenance": make_provenance("lb_multi_label", "deterministic", []),
        })
    return findings


# ---------------------------------------------------------------------------
# IC power pin DC path audit (PP-001)
# ---------------------------------------------------------------------------

# Module-internal LDO rail names — these nets are fed from an internal LDO
# inside the IC and only need external decoupling, not an external DC source.
# Demote PP-001 from error to info for these (KSZ8041, STM32 internal regs,
# Atmel internal cores, etc.).
_MODULE_INTERNAL_RAIL_PATTERNS = (
    'VDDPLL',                # PLL-domain internal rail (KSZ8041, STM32, ATmega)
    'VDDA_INT', 'VDDAINT',   # analog-domain internal core (Atmel, NXP)
    'VDDCORE', 'VDD_CORE',   # core-voltage internal rail (NXP LPC, Renesas)
    'VDDIO_INT', 'VDDPHY',   # PHY/IO-domain internal (Ethernet PHYs)
    'VCAP',                  # STM32 internal-regulator cap pin
    'VDDREG',                # internal regulator output (decoupling only)
)


def _is_module_internal_rail(net_name: str) -> bool:
    """True if the net name matches a known module-internal LDO rail pattern.
    These nets are driven by an internal regulator and only require external
    decoupling — they should NOT be flagged as missing-DC-source by PP-001.
    """
    if not net_name:
        return False
    base = net_name.upper().lstrip('/').lstrip('+')
    return any(base.startswith(pat) for pat in _MODULE_INTERNAL_RAIL_PATTERNS)


def _is_bootstrap_pin_name(pin_name: str) -> bool:
    """True for BST, BOOT, CBST, BOOT1, BST_A, ... (any _ or / token)."""
    tokens = re.split(r"[_/]", (pin_name or "").upper())
    return any(t.rstrip("0123456789") in _BOOTSTRAP_PIN_TOKENS for t in tokens)


def audit_power_pin_dc_paths(ctx: AnalysisContext,
                             solder_jumpers: list[dict] | None = None,
                             bridge_facts=None,
                             power_regulators: list[dict] | None = None) -> list[dict]:
    """For every IC power_in pin, prove a DC path to a power rail exists.

    A power_in pin that only reaches ground through a capacitor is
    AC-coupled — the IC's supply floats DC, ERC is silent, and the
    board behaves unpredictably. Walk the net graph starting at each
    power_in pin, crossing:
      - wires on the same net                           (free)
      - resistors with parsed value <= 1 Ω              (bridge)
      - inductors / ferrite beads                       (bridge)
      - fuses / polyfuses                               (bridge)
      - solder jumpers with default_state='bridged'    (bridge)
    and REJECT crossing capacitors. If no named power rail is reachable
    within 2 hops, emit PP-001 at severity=error (info on module-internal LDO rails).
    A net known as a rail only from its pins (a supply pin and a capacitor to ground)
    counts as reached unless it is AC-coupled: only IC pins and capacitors sit on it,
    a two-pin capacitor joins it to another rail, and it shows no source of its own
    (a power_out pin, a PWR_FLAG or a regulator output). Then the walk goes on, as for
    an unnamed net.
    """
    findings: list[dict] = []
    nets = ctx.nets or {}
    components = {c.get("reference"): c for c in (ctx.components or [])}
    reg_output_nets = {reg.get("output_rail") or reg.get("vout_net")
                       for reg in (power_regulators or [])} - {None, ""}

    # Map component ref -> list of (pin_number, net_name, pin_type) for net hops.
    ref_pins = build_ref_pins(nets)
    if bridge_facts is None:
        bridge_facts = build_bridge_facts(
            ctx.components or [], ref_pins, solder_jumpers)
    ties = tie_conductors(bridge_facts)

    def _has_source(net: str) -> bool:
        info = nets.get(net, {})
        return (bool(info.get("has_pwr_flag")) or net in reg_output_nets
                or any(str(p.get("pin_type") or "").split("+")[0] == "power_out"
                       or (p.get("component") or "").startswith("#FLG")
                       for p in info.get("pins", [])))

    def _ac_coupled(net: str) -> bool:
        # Only IC pins and capacitors on the net, and a two-pin capacitor from it
        # to another (non-ground) rail: the supply reaches the pin through a cap.
        to_rail = False
        for p in nets.get(net, {}).get("pins", []):
            cref = p.get("component") or ""
            kind = (components.get(cref) or {}).get("type")
            if kind == "ic" or cref.startswith("#"):
                continue
            if kind != "capacitor":
                return False
            far = {n for _pn, n, _pt in ref_pins.get(cref, []) if n != net}
            if len(ref_pins.get(cref, [])) == 2 and len(far) == 1:
                (far_net,) = far
                to_rail = to_rail or (ctx.is_power_net(far_net) and not ctx.is_ground(far_net))
        return to_rail

    def _is_dc_rail(net: str) -> bool:
        if ctx.is_ground(net) or not ctx.is_power_net(net):
            return False
        if ctx.is_power_net(net, by_pins=False):
            return True
        return _has_source(net) or not _ac_coupled(net)

    # Component-type-based bridge predicate.
    def _bridges_dc(ref: str) -> bool:
        fact = bridge_facts.by_ref.get(ref)
        if fact is None:
            return False
        if fact.kind in ("inductor", "ferrite_bead", "fuse"):
            return True
        if fact.kind == "resistor":
            # Small value resistors count as DC-conductive.
            return fact.resistance is not None and fact.resistance <= 1.0
        if fact.kind == "jumper":
            return fact.default_state == "bridged"
        return fact.kind == "net_tie"

    def _is_capacitor(ref: str) -> bool:
        c = components.get(ref) or {}
        return (c.get("type") or "").lower() == "capacitor"

    def _is_connector(ref: str) -> bool:
        """Return True if ref looks like a connector (external supply entry point)."""
        c = components.get(ref) or {}
        t = (c.get("type") or "").lower()
        if t in ("connector",):
            return True
        # J<digit> / P<digit> reference prefixes are conservative connector
        # heuristics; other connector refs must carry type="connector" in the
        # component dict (caught by the preceding check).
        return bool(ref and ref[0] in ("J", "P") and ref[1:2].isdigit())

    # Build per-net connector presence set — nets with connectors may have
    # external DC supply; suppress PP-001 for those nets to avoid false
    # positives on boards where the power comes in from a header.
    nets_with_connector: set[str] = set()
    for net_name_c, net_info_c in nets.items():
        for p in net_info_c.get("pins", []):
            cref = p.get("component") or ""
            if _is_connector(cref):
                nets_with_connector.add(net_name_c)
                break

    MAX_HOPS = 2
    # Track (ref, pin, net) triples already checked to avoid duplicate findings.
    seen: set[tuple[str, str, str]] = set()

    for net_name, net_info in nets.items():
        for p in net_info.get("pins", []):
            if p.get("pin_type") != "power_in":
                continue
            ref = p.get("component") or ""
            pin_num = str(p.get("pin_number", ""))
            pin_name = p.get("pin_name") or ""
            if not ref or ref.startswith("#"):
                continue  # PWR_FLAG / power symbol virtuals

            # Ground pins (VSS, GND, AGND, SGND, VSSA, etc.) are already
            # at the ground reference — they don't need a path to a positive
            # power rail. Flagging them would be a false positive.
            # A net tied to ground is ground too (one conductor).
            if any(ctx.is_ground(n) for n in conductor_of(ties, net_name)):
                continue

            if _is_bootstrap_pin_name(pin_name):
                continue

            # If a connector is on this net, external DC supply is plausible.
            # Suppress — the RS-001 rule handles "no declared source" separately.
            if net_name in nets_with_connector:
                continue

            # The net is part of the key: duplicate / unannotated refs (U? x N) share (ref, pin).
            key = (ref, pin_num, net_name)
            if key in seen:
                continue
            seen.add(key)

            frontier: set[str] = {net_name}
            visited: set[str] = {net_name}
            # A power_in pin directly on a DC rail is already fed.
            reached_rail = _is_dc_rail(net_name)
            # Track whether any capacitor blocked the walk — only emit PP-001
            # when a cap-only path exists (not just "no source declared").
            # That distinguishes the AC-coupling bug from missing-PWR_FLAG
            # which RS-001 already covers.
            saw_capacitor_on_path: bool = False
            for _hop in range(MAX_HOPS):
                if reached_rail:
                    break
                next_frontier: set[str] = set()
                for cur_net in frontier:
                    cur_info = nets.get(cur_net, {})
                    for cp in cur_info.get("pins", []):
                        cref = cp.get("component") or ""
                        if not cref or cref == ref:
                            continue
                        if _is_capacitor(cref):
                            saw_capacitor_on_path = True
                            continue
                        if not _bridges_dc(cref):
                            continue
                        for _other_pn, other_net, _pt in ref_pins.get(cref, []):
                            if other_net == cur_net:
                                continue
                            if other_net in visited:
                                continue
                            visited.add(other_net)
                            next_frontier.add(other_net)
                            if _is_dc_rail(other_net) or other_net in nets_with_connector:
                                reached_rail = True
                frontier = next_frontier
                if not frontier:
                    break

            if reached_rail:
                continue
            # Only emit if a capacitor was present on the path — this is the
            # specific "AC-coupled supply" wiring bug PP-001 targets. Pins on
            # nets with no source at all (no PWR_FLAG, no regulator output)
            # are already flagged by RS-001 and don't need a second finding.
            if not saw_capacitor_on_path:
                continue

            pin_label = f"{ref}.{pin_num}"
            if pin_name:
                pin_label += f" ({pin_name})"
            # Module-internal LDO rails (VDDPLL_*, VDDA_INT_*, VDDCORE_*, etc.)
            # are driven by an INTERNAL regulator inside the IC — they don't
            # need an external DC source, only decoupling. Demote to info.
            _is_internal_rail = _is_module_internal_rail(net_name)
            _severity = 'info' if _is_internal_rail else 'error'
            _summary_prefix = (
                f"IC power pin {pin_label} on internal-LDO rail "
                f"(net {net_name!r}) — decoupling-only is correct"
                if _is_internal_rail else
                f"IC power pin {pin_label} has no DC path to a "
                f"power rail (net {net_name!r})"
            )
            findings.append({
                "detector": "audit_power_pin_dc_paths",
                "rule_id": "PP-001",
                "severity": _severity,
                "confidence": "heuristic",
                "evidence_source": "topology",
                "category": "power",
                "summary": _summary_prefix,
                "description": (
                    f"Pin {pin_label} is type=power_in on net {net_name!r} "
                    f"which matches a module-internal LDO rail naming "
                    f"convention. The IC supplies this rail from an "
                    f"internal regulator; only external decoupling is "
                    f"required. No external DC source needed."
                    if _is_internal_rail else
                    f"Pin {pin_label} is type=power_in on net "
                    f"{net_name!r}. Graph walk (≤{MAX_HOPS} "
                    f"hops, rejecting capacitor edges, "
                    f"accepting resistors≤1Ω, inductors, "
                    f"ferrite beads, bridged solder jumpers) "
                    f"did not reach a named power rail. The pin "
                    f"is likely AC-coupled to ground only — "
                    f"the IC will not power up reliably."),
                "components": [ref],
                "nets": sorted(visited)[:10],
                "pins": [pin_label],
                "start_net": net_name,
                "visited_nets": sorted(visited),
                "source_path": "none",
                "recommendation": (
                    "Verify against the datasheet that this pin is an "
                    "internal-LDO output. If so, confirm a 0.1µF (or "
                    "datasheet-recommended) decoupling cap to GND is "
                    "present. Otherwise, route an external DC source."
                    if _is_internal_rail else
                    "Verify the schematic for this pin: the DC route must "
                    "go through a conducting element (direct wire, 0Ω "
                    "resistor, inductor, ferrite bead, or bridged solder "
                    "jumper) — not a capacitor. If the intent was to tie "
                    "VCC through an LC filter, add the missing inductor "
                    "or 0Ω in series."),
                "report_context": {
                    "section": "Power — DC Continuity",
                    "impact": ("Module-internal rail — decoupling-only is correct."
                               if _is_internal_rail else
                               "IC supply floats DC; board will not run."),
                    "standard_ref": "",
                },
                "provenance": make_provenance("pp_dc_path_audit", "deterministic", [ref]),
                "schema_era": "v3.0",
            })

    return findings

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall