concur

Cross-source consensus check for chip libraries.

A small Rust CLI that runs downstream of ds2sf and chip-fetcher: it loads every available source-of-truth for a chip's symbol and footprint (datasheet-extracted, KiCad UL bundle, Fusion 360 EAGLE .lbr, Altium binary), compares them across seven axes, and emits a result.json with status: golden | divergent | unrecoverable plus tagged hints[] so the upstream caller can either re-fetch a suspect library or escalate to a human.

The pipeline:

chip-fetcher  →  ds2sf (status: ok)  →  concur (status: golden)  →  downstream is happy
                                            ↓ divergent
                                       chip-fetcher refetches a lib
                                       OR human reviews

Why this matters

Concur is opinionated about whether a divergence requires upstream work or is safe to ship. Many "disagreements" between sources are known-benign patterns (exposed-pad counted as pin N+1 in one source but not the other, JEDEC-outline-name vs marketing-name, alt-function pin labels, pad-array span misread as body dim). Concur classifies these as variants and ships the dataset with status: golden_with_variants (exit 0) so the upstream caller can move forward and just remember the variants downstream. Real disagreements stay divergent (exit 2).

Real example from this release's smoke tests:

$ concur check ~/project/chip-fetcher/library/ADS1115IDGSR
  ds2sf       — 10 pins, 10 pads, package "VSSOP-10"
  kicad       — 10 pins, 10 pads, footprint "SOT_ADS1115IDYNR_TEX"
  eagle (.lbr) — 10 pins, 10 pads, package "DGS0010A_N"

OK: ADS1115IDGSR — GOLDEN with variants [variants: label_only, stub_pin_names, body_dim_artifact]

What concur figured out:

• label_only_mismatch — KiCad's footprint name starts with SOT_ because that's TI's UL library prefix convention, but the geometry (pad count, pad layout, pitch) all agrees with EAGLE's DGS0010A_N and ds2sf's VSSOP-10. The package family really is VSSOP. Cosmetic only.
• stub_symbol_pin_names — the KiCad UL symbol has pin "names" of "1", "2", "3"… instead of real labels. Downstream can use ds2sf's or EAGLE's pin labels.
• body_dim_measurement_artifact — ds2sf and EAGLE report different body dimensions (5.05×3.10 vs 4.45×2.00). Body dim is courtyard-only, doesn't affect placement; the diff is a measurement-method artifact (lead-tip span vs pad-array span vs body D dim).

All three are flagged but explained, exit 0, chip-fetcher moves forward.

Outputs

<chip-dir>/<MPN>-concur.result.json — the audit + agent contract:

{
  "schema_version": "1",
  "status": "golden_with_variants",
  "exit_code": 0,
  "mpn": "ADS1115IDGSR",
  "summary": "ADS1115IDGSR — GOLDEN with variants [variants: label_only,stub_pin_names,body_dim_artifact]",
  "sources_compared": ["ds2sf","kicad","eagle"],
  "sources_missing":  ["altium"],
  "variants": [
    { "kind": "label_only_mismatch",
      "notes": "ds2sf: VSSOP-10 → family=VSSOP | eagle: DGS0010A_N → family=VSSOP | kicad: SOT_ADS1115IDYNR_TEX → family=SOT" },
    { "kind": "stub_symbol_pin_names",
      "stub_sources": ["kicad"],
      "canonical_sources": ["ds2sf","eagle"] },
    { "kind": "body_dim_measurement_artifact",
      "notes": "ds2sf: 5.05×3.10 mm | eagle: 4.45×2.00 mm" }
  ],
  "axes": [
    { "axis": "pad_count",     "verdict": "agree" },
    { "axis": "pin_names",     "verdict": "disagree",
      "conflicts": ["kicad has stub-only pin names …"] },
    { "axis": "package_family","verdict": "disagree",
      "conflicts": ["Package families disagree across sources: ds2sf=VSSOP, kicad=SOT, eagle=VSSOP"] }
  ],
  "hints": [
    { "action": "ul_symbol_has_stub_names", "source": "kicad", "pin_count": 10,
      "suggestion": "Use ds2sf-extracted symbol JSON or refetch the .kicad_sym from a manufacturer-direct source" }
  ]
}

Status ladder

Variant kinds (v0.3)

Comparison axes

Agent-to-agent contract

hints[] is a tagged-union list (separate from variants[] — variants explain why a disagreement is benign; hints tell the caller what action to take). v0.3 enriches refetch hints with concrete suggested_sources (priority-ordered) and expected_resolution so chip-fetcher knows where to refetch from AND how to verify the refetch worked.

Calling recipe

let r = run_concur(chip_dir);
match r.status.as_str() {
    "golden" => mark_chip_dir_clean(),
    "divergent" => {
        for h in &r.hints {
            match h {
                Hint::RefetchLibrarySource { format, .. } => {
                    refetch_lib_from_alternate_source(format);
                    return run_concur(chip_dir); // re-call after refetch
                }
                Hint::UlSymbolHasStubNames { .. } => {
                    // Replace .kicad_sym from ds2sf JSON via downstream sym_create.
                }
                _ => {}
            }
        }
    }
    "unrecoverable" => log_for_human(&r),
    _ => unreachable!(),
}

CLI

concur check <CHIP-DIR>     # run cross-source check
concur inspect <CHIP-DIR>   # print summary of an existing concur.result.json
concur health               # parser readiness check
concur install              # drop SKILL.md

check flags: --ds2sf-symbol, --ds2sf-footprint, --kicad-sym, --kicad-mod, --eagle, --mpn, --out-dir, --force, --json-only.

Validated chips (v0.3 release — 9-chip suite)

7/9 pass cleanly (golden_with_variants exit 0). 2/9 are real wrong-variant findings the upstream caller should refetch. Zero false positives in v0.3.

Out of scope (current)

• Altium .SchLib (symbol-side) parsing. v0.6 added .PcbLib (pads) via the sister altium-pcblib crate; .SchLib pin labels are still pending.
• Body-thickness comparison (z-dim). Sources don't reliably report this.
• Tolerance-aware lead/pad-pitch checks beyond raw body dims.

Altium multi-variant selection (v0.7)

Many vendor .PcbLibs ship multiple footprint variants in the same file — for example DRV8316RRGFR carries RGF0040E-IPC_A (41-pad IPC standard) AND RGF0040E-MFG (57-pad manufacturing layout with extra fiducials and test points). The upstream altium-pcblib crate picks one as "primary" by stream order.

If concur naively trusts the primary, it can disagree with kicad+eagle 100% of the time. v0.7 computes the pad-count consensus from already-parsed sources (ds2sf / kicad / eagle) and asks altium-pcblib for the variant whose pad count is closest to the median. Names containing -MFG / _MFG / DEBUG / FIDUCIAL / TEST get a tiebreak penalty so the IPC-standard variant wins when in doubt.

Effect on the benchmark: DRV8316RRGFR was reporting divergent with altium engaged (57 vs 41) → now reports golden_with_variants (41 across all four sources, only EP-counting differs).

Build

cargo build --release
sudo cp target/release/concur /usr/local/bin/
concur install

Or just ./build.sh.

Related

• ds2sf — datasheet → symbol + footprint + provenance JSON. Upstream of concur.
• chip-fetcher — pulls the libraries that concur cross-checks.