Unify controller transports and preserve both histories for the future repository merger #41

Goal and boundaries

Coordinate atomicdeploy/PakarController and atomicdeploy/PCController toward one repository and one production firmware source tree, without losing either unrelated Git history, useful implementation, tests, licenses, settings or host work. Pealayer remains a coordinated consumer where its contract is affected. Do not perform an unrelated-history merge merely to close this issue.

This pass

• Inventory every implemented framing, carrier, envelope, request/result/event contract, transfer path, client and build profile; distinguish source, fixture, build, runtime and hardware proof.
• Preserve USB/UART/CDC recovery and specialized bootloader protocols. COBS is framing, not a competing USB transport. Existing raw opcode namespaces collide (Pakar0x11 audio versus PC0x11 PWM); never remove their admission boundary blindly.
• Share malformed/golden/maximum-size fixtures and harden parsers without changing valid wire bytes. Keep CRC corruption detection separate from authentication.
• Measure feature/resource deltas and expose real build-selected limits/capabilities; slim builds must explicitly reject unavailable operations, never silently acknowledge no-ops.

Next pass: shared semantics and parity

• Select one source owner for portable framing, typed operation registry, identity/boot/session fencing, correlation, cancellation, deadlines, errors and events. Reuse superior existing implementations rather than creating another protocol.
• Use additive optional fields/capability discovery, stable numeric IDs and bounded unknown-field handling. Do not use exact release equality, schema generations, version-selected adapters or silently reinterpret ambiguous old opcodes.
• Define and test stream/datagram differences: reliable control/maintenance versus lossy frame streaming, fragmentation/reassembly, replay protection, leases, subscriptions, backpressure and state resynchronization. Never retry an outcome-unknown mutation.
• Complete advertised API/command/event/firmware/file capabilities consistently across enabled USB/UART/OTG, TCP/HTTP/WebSocket, MQTT, UDP and BLE adapters; explicitly advertise exclusions, authentication and real size limits.

Following pass: MCU portability and merger

• Retain the one production AVR source tree, shared with native conformance targets. Existing ATmega328P and Mega2560 are separate pin/timer/storage/toolchain profiles, not copied firmwares. Coordinate PCController#103/#227/Bump the cargo-dependencies group in /desktop with 3 updates #18/#125/#375 and PakarController#3/Complete PCController current-hardware contracts and gated future hardware #6/Apply the living unversioned API policy across firmware and all clients #16.
• Isolate MCU HAL seams (GPIO, UART/USB, clocks/timers, storage, interrupts, buses, reboot/watchdog, LED drivers). Add actual STM32/ESP implementations only for selected chips/pinouts/toolchains and verified budgets; no unsupported target is advertised as functional.
• Preserve EEPROM/LittleFS/settings backups and define guarded semantic imports; raw PC/Pakar EEPROM layouts are incompatible.
• Inventory and reconcile worktrees, branches, stashes, PR conversations, failing checks and owner drafts in both repositories before merger; no force/reset/wholesale uncertain merges or check bypass.
• Capture immutable refs/tags and source manifests; stage a reviewed git merge --allow-unrelated-histories that retains both graphs and original commit IDs. Compare EVERY overlapping and unique file using the existing donor ledger: owner, hashes, retained behavior, tests, licenses, omissions and remaining acceptance. No copy-flattening or silent deletion.
• Consolidate duplicate code only after behavior/tests have a named canonical owner. Retain boards/business roles as build-selected profiles and clients as targets of the same living contract.
• Gate the final default branch on full CI, cross-language/device interoperability, queue/loss/reconnect/soak tests, slim/full flash/RAM/stack budgets and commissioning/rollback evidence. Publish clean exact refs and remaining hardware gates; source tests alone do not establish production completion.

Acceptance

No partial transport is advertised as complete. Both repositories benefit before the eventual merger; all useful donor behavior is retained or explicitly tracked. Clients discover capabilities and limits, optional additions remain tolerant, and unsupported safety-critical semantics fail closed. Hardware and deployment require their own authorization and evidence.

Shared contract/core implementation owners and carrier completion

The current requirement is one shared semantic command/event contract and portable core, with complete enabled adapters, not a single oversized wire envelope.

• Canonical operations, capabilities, request correlation, errors, events, deadline/cancel rules, subscriptions and transfers: Generate protocol, settings, hardware, and capability definitions from canonical contracts PCController#125.
• Authoritative enabled-carrier/profile/client parity matrix and adapter fault tests: Unify embeddable and local IPC transports behind one control-plane contract PCController#375. Its matrix explicitly separates existing partial paths, documented gaps, unverified cells, service-role exclusions and omitted adapters.
• Board/peer compact framing and additive field evolution: Define durable unversioned COBS/TLV evolution across board and host peer links PCController#377. Routing/identity/authority: Define durable capability-negotiated board-PC-PC routing and active-branch integration PCController#366. Preserve the existing owners rather than create another dispatcher or duplicate matrix.
• Pakar implementation links: Complete PCController current-hardware contracts and gated future hardware #6/Remote firmware transaction, full operational telemetry and PU850 route acceptance #7/Contextual board discovery and independently acknowledged UI #10/Apply the living unversioned API policy across firmware and all clients #16/ESP32-S3 Bluetooth LE and Flutter offline control #20/Managed LittleFS file browser, integrity transfers and optional microSD #28/Integrate pinned portable-shell source without regressing device ownership #29/ESP32-S3 native SSH transport for the shared device shell #33 in atomicdeploy/PakarController; Pealayer integration: Integrate embedded PCController and OS-native local IPC fallback ToghrolTP/pealayer#32. Complete Rust/Flutter/Web/Go consumer parity against the same supported semantic services.
• For every enabled carrier and build budget, every applicable operation/event/client cell must pass or have an explicit accepted, machine-checked slim/service-role exclusion. Record flag, reason/resource figures, absent advertisement and deterministic Unsupported behavior. Unknown or partially implemented is not an exclusion.
• Keep reliable control/maintenance separate from lossy streaming and specialized recovery. USB/UART/CDC are carriers; COBS is framing. MQTT QoS, a UDP receipt, an HTTP queued job or a USB chunk ACK is not verified hardware completion. Never replay an outcome-unknown mutation over a fallback route.
• Preserve existing conflicting raw opcode namespaces (native A5/1 vs Pakar A5/0; 0x11 PWM vs audio), HELLO/settings/event shapes and critical admission. One semantic operation catalogue needs explicit namespace adapters; sharing COBS/CRC cannot make those packets interchangeable.
• Keep compact, caller-bounded MCU representations with portable clock/I/O/HAL seams. Do not impose DGLU host buffers, desktop serialization or universal transfer envelopes on AVR.
• All shared API evolution remains living/unversioned and additive/capability-based; no product generation selectors, exact-release adapters or silent policy downgrade.

Evidence already available, not full completion

PCController#704 is merged at 8b0ea74a347f656640cfda244582802ac0d09517: canonical native/Pakar allocation ownership, generated consumer views, published-ID stability and strict namespace checks. Pakar#43 and Pealayer#223 are related consumer checkpoints, not proof of complete payload, carrier, client or deployment parity. Earlier strict COBS/fragment fixtures also remain useful. Do not tick the full semantic/core/adapter requirements solely from those tests.

The future unrelated-history/source-tree merger, full MCU HAL work, preserved settings/rollback and real-device/LAN/soak gates above remain open. This issue update does not flash, reset, actuate or reconfigure production.