feat: introduce Network framework transport prototype

[rchatham]

Summary

Introduce the framework-neutral seams and initial Network.framework transport prototype that anchor the migration while preserving the existing public API and MultipeerConnectivity-backed default behavior.

Changes

• Add the migration architecture plan, dependency inventory, staged rollout, risks, and test strategy.
• Add internal transport seams around session, browser, advertiser, and advertiser-assistant responsibilities.
• Introduce framework-neutral PeerIdentity while keeping Peer source-compatible.
• Add Bonjour service naming, handshakes, bounded framed messages, and a stream-safe decoder.
• Add prototype NWConnection, NWListener, and NWBrowser transports with peer-to-peer enabled.
• Add coordinator, registry, duplicate resolution, state mapping, data sending, self filtering, mutation serialization, and cleanup foundations.
• Integrate existing security configuration, invitation policy, discovery metadata, public compatibility, demo, and tests through the seams.
• Use secure keyed archiving for deterministic Multipeer-backed peer identifiers while preserving legacy identifiers.
• Propagate handshake encoding failures instead of reporting false success.
• Decode large coalesced frame batches without repeated buffer shifting.

Compatibility

This checkpoint does not publicly select the Network backend. Existing public behavior remains MultipeerConnectivity-backed. multipeerSession remains the largest public compatibility constraint for eventual MC removal.

Verification

• swift test — 110 tests passed locally after review fixes.
• iPhone 16 / iOS 18.3.1 Xcode tests — 110 tests passed locally.
• Added deterministic/legacy peer-identity, handshake-failure, and 10,000-frame coalesced/partial decoder regression coverage.
• Correctness and security reviews found no blockers.

Follow-ups

Public backend selection, TLS-PSK, lifecycle reliability, browser UX, parity decisions, production trust, and migration guidance are intentionally layered in later checkpoints.

Stack

• Base: master
• Child: feat: add Network migration infrastructure and opt-in backend #57

[Copilot]

Pull request overview

This PR starts an internal migration toward a Network-framework-backed transport by introducing transport seams (session/browser/advertiser/assistant), a framework-neutral peer identity model, and a first-cut Network protocol/framing prototype—while keeping the existing public API MultipeerConnectivity-backed.

Changes:

• Introduces internal transport protocols + a factory to inject MultipeerConnectivity (now) and future Network-backed implementations.
• Adds PeerIdentity and updates Peer equality/hash/displayName to be identity-based.
• Adds Network protocol primitives (Bonjour service naming, handshake, frame encoding/decoding) plus prototype Network transport/coordinator/registry utilities and associated unit tests.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
Sources/PeerSession.swift	Makes PeerSession conform to PeerSessionTransport and exposes multipeerSession.
Sources/PeerConnectionManager.swift	Switches internals to transport protocols and adds an injectable transport factory initializer.
Sources/PeerConnectionTransports.swift	Adds internal transport protocols and a MultipeerConnectivity-backed factory.
Sources/PeerBrowser.swift	Uses PeerSessionTransport and routes invites via multipeerSession.
Sources/PeerAdvertiser.swift	Uses PeerSessionTransport for advertiser construction.
Sources/PeerAdvertiserAssisstant.swift	Uses PeerSessionTransport and routes assistant session via multipeerSession.
Sources/PeerAdvertiserEventProducer.swift	Updates invitation handler to operate on PeerSessionTransport.
Sources/PeerIdentity.swift	Adds framework-neutral PeerIdentity.
Sources/Peer.swift	Refactors displayName/equality/hash to be identity-based; adds MCPeerID→PeerIdentity mapping.
Sources/PeerNetworkProtocol.swift	Adds Bonjour service mapping, handshake model, framing, and streaming decoder.
Sources/NetworkPeerTransport.swift	Adds NWConnection/NWListener/NWBrowser wrappers (prototype).
Sources/NetworkPeerStateMapping.swift	Adds mapping helpers from NWConnection.State to Peer.Status semantics.
Sources/NetworkPeerConnectionRegistry.swift	Adds a registry with duplicate-connection resolution.
Sources/NetworkPeerDataSender.swift	Adds a data sender for framed sends over registry connections.
Sources/NetworkPeerCoordinator.swift	Adds handshake/data/discovery coordination + event emission into existing Observables.
PeerConnectivityTests/PeerIdentityTests.swift	Tests identity-backed Peer displayName/equality semantics.
PeerConnectivityTests/PeerNetworkProtocolTests.swift	Tests Bonjour naming, handshake encoding, frame encode/decode, streaming decoder behavior.
PeerConnectivityTests/PeerConnectionManagerTransportTests.swift	Verifies manager behavior via injected transport mocks.
PeerConnectivityTests/NetworkPeerStateMappingTests.swift	Tests state→status mapping utilities.
PeerConnectivityTests/NetworkPeerConnectionRegistryTests.swift	Tests duplicate resolution and cancellation behavior.
PeerConnectivityTests/NetworkPeerDataSenderTests.swift	Tests broadcast/targeted sending over registry connections.
PeerConnectivityTests/NetworkPeerCoordinatorTests.swift	Tests handshake registration, data events, duplicate handling, and discovery filtering.
PeerConnectivity.xcodeproj/project.pbxproj	Adds new source and test files to Xcode project.
NetworkFrameworkMigrationPlan.md	Adds a migration plan document for moving toward Network framework.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.