gokul/cm4-media-carrier

UPSTREAM_FINDINGS.md

# Consolidated tscircuit findings — 2026-10-28

Only the following export problems were confirmed in the real carrier workflow. Both have release-package workarounds. No new issue or PR has been filed by this task.

## Rotated footprint libraries disagree with their board instances

Affected export: `circuit-json-to-kicad` 0.0.255 (also observed with 0.0.252), using `CircuitJsonToKicadPcbConverter` and `CircuitJsonToKicadLibraryConverter` on this carrier. KiCad 10.0.5 reports three `lib_footprint_mismatch` warnings for the rotated USB-C, HDMI and Micro-B connectors. The library is found and parsed successfully. The board itself has no disconnected copper or clearance errors.

The first incorrect stage is the library's conversion to local footprint coordinates/orientations: its rotated pad geometry does not equal the footprint embedded in the PCB. This matters when a user runs native KiCad DRC or updates the PCB from its accompanying library. An update from the mismatched library could change land geometry. The independent native audit verifies the board's 285 pad centres, dimensions, pin numbers and named nets against Circuit JSON; it reports zero mismatches.

Reproduce using `tools/export.ts` on `manufacturing/circuit.json` into a new directory, then run native KiCad DRC **before** `tools/native-audit.py`. The latter applies the release workaround: normalize rotated library footprints with KiCad's own footprint writer, without changing the board file. The final package passes native DRC with zero violations. The baseline three warnings are preserved in `validation/library-repro-drc.json`.

Existing issues/PRs were searched using footprint/library/rotation terms. [PR #593](https://github.com/tscircuit/circuit-json-to-kicad/pull/593) fixes an importer bottom-rotation round trip, not this library parity problem. A focused library-normalization reproduction is a worthwhile contribution candidate; recheck for duplicates before opening one.

## Numeric generator_version must be quoted in footprint files — already tracked

The library exporter emits `(generator_version 8.0)`. Native KiCad rejects the numeric token where it expects a string, causing misleading library-not-found/parity warnings for otherwise valid footprints. Quoting it as `(generator_version "8.0")` lets the native parser load them. The release export script performs only that metadata correction before the independent native pad audit.

This is already covered by open [tscircuit/kicadts PR #66](https://github.com/tscircuit/kicadts/pull/66). Do not open a duplicate.

## Observations excluded from the issue list

Default paste reduction and mixed-mount paste were handled with supported source controls and explicit top stencil geometry. Supplier pick-and-place rotation warnings correctly indicate absent feeder-library evidence; the release supplies exact physical pin-1 positions for assembler mapping. Alpha Gerber-viewer polarity/rotation limitations were cross-checked against actual parsed files. Those observations are not presented as new tscircuit bugs. Board placement corrections and earlier incorrect API usage were design-work mistakes, not upstream defects.