Scaffold Swift-implemented drop-in replacement for libbluetooth.so.3

[colemancda]

Summary

Scaffolding for a drop-in, Swift-implemented replacement for BlueZ's shared libbluetooth.so.3. The deliverable is a library that loads, resolves all 218 symbols the reference exports, and fails loudly (by symbol name) on any call not implemented yet — so the rest of the port can proceed incrementally, one symbol family at a time.

Nothing in the bluez package actually links this shared library — bluetoothd, bluetoothctl, btmon, hciconfig and sdptool all statically link libbluetooth-internal.a — so replacing it can't break the Bluetooth stack itself; it exists solely for third-party consumers.

• Sources/CBluetoothLinuxABI vendors the eleven public BlueZ headers verbatim (GPL-2.0-or-later, isolated in its own directory with its own LICENSE and README) and generates a stub for every symbol not yet implemented, via scripts/gen_stubs.py. Each stub's signature is read out of the vendored headers, so it's checked against the real declaration rather than hand-typed.
• scripts/symbols.txt records the reference export surface (218, split 17/101/100 across bluetooth.c/hci.c/sdp.c); scripts/implemented.txt records the 203 currently implemented: the bluetooth.c + bt_uuid_* families and the SDP data/list/record/codec layer (both implemented in PureSwift/Bluetooth), plus this repo's own HCI string converter family, HCI device management family, and the 71-symbol HCI command wrapper family (hci_inquiry, hci_create_connection, hci_read_*, hci_write_*, hci_le_*, etc.) — everything BlueZ's lib/hci.c exports except hci_strtoptype-adjacent string helpers already covered above. scripts/gen_symbols.py derives the linker version script and the flat export list from these; scripts/check-exports.sh asserts the built library against it.
• scripts/ownership.md records the return/who-frees/lifetime contract for each symbol, ahead of implementation — the conventions aren't uniform (some allocate on the heap, some write into a caller buffer, some return static pointers) and guessing produces leaks or double frees no type checker would catch.
• Sources/BluetoothLinuxABI implements the 21-symbol HCI string converter family, using generated lookup tables (scripts/generate-hci-tables.py, parsed directly from BlueZ's hci.c) for the bus/device-flag/packet-type/link-mode/version/command-name mappings; the 9-symbol HCI device management family (raw AF_BLUETOOTH/BTPROTO_HCI socket open/close, device info/address/id lookup, enumeration, routing, and sending commands/requests); and the 71-symbol HCI command wrapper family (connection/link-policy management, remote-device queries, local controller info, controller configuration, LE commands, and inquiry) built on hciCommand/hciStatus/hciRequest helpers that capture the send/check-status/copy-out shape every wrapper in lib/hci.c repeats. All of it talks to the kernel directly via socket/bind/ioctl/writev/poll rather than through BluetoothLinux's own async HostController/Socket infrastructure, since the ABI surface has to be synchronous and match the reference's wire layout precisely.
• CMakeLists.txt builds libbluetooth.so.3.19.15 by linking a PureSwift/Bluetooth checkout's static archives (-DBLUETOOTH_PACKAGE_PATH) together with BluetoothLinuxABI and the generated stubs, with the soname, version, and a pinned export list that Package.swift can't express.
• Conformance/compare.sh and Conformance/conformance_hci_strings.c differentially test the HCI string converter family against the system libbluetooth.so.3; the phase-1 and SDP drivers stay in the PureSwift/Bluetooth checkout alongside the symbols they cover.

Verified

• The built library exports exactly the 218 expected symbols (check-exports target).
• Its output over the differential conformance drivers for the symbols with a driver (bluetooth.c/bt_uuid_*, SDP, HCI strings) is identical to the system libbluetooth.so.3, aside from a handful of already-documented deltas (bt_compidtostr naming, one memcmp-magnitude case) recorded in each repo's known-differences.txt.
• Calling an unimplemented symbol (e.g. hci_open_dev) aborts with libbluetooth (PureSwift): hci_open_dev is not implemented yet. rather than crashing unhelpfully or corrupting state.

Test plan

• swift build — default configuration, unaffected
• SWIFTPM_BLUETOOTH_CABI=1 swift build — C ABI target builds
• SWIFTPM_BLUETOOTH_CABI=1 swift test — passes, including the new BluetoothLinuxABITests
• cmake -B build -G Ninja -DBLUETOOTH_PACKAGE_PATH=<Bluetooth checkout> && cmake --build build — libbluetooth.so.3.19.15 builds
• cmake --build build --target check-exports — 218/218 symbols match
• Conformance/compare.sh — identical output against the reference library for the HCI string converter driver
• Smoke test: an unimplemented symbol aborts loudly by name instead of misbehaving

Known gap

hci_send_cmd/hci_send_req and everything built on them — the entire 71-symbol HCI command wrapper family, plus hci_inquiry's ioctl(HCIINQUIRY) call — have not been exercised against a real or virtual HCI device. Only their non-socket paths (input validation, hci_send_cmd's wire-format framing over a plain pipe) are unit tested. No /dev/vhci access was available (root-only in this environment) to build a differential driver for this family; each wrapper is a careful, field-by-field transcription of its lib/hci.c reference, cross-checked against the vendored struct layouts, but unverified end-to-end.