feat: add Network migration infrastructure and opt-in backend

[rchatham]

Summary

Turn the initial Network.framework prototype into a safely selectable backend with the migration infrastructure required by later work.

Changes

• Add the Network migration CI baseline and framework-neutral compile/test coverage.
• Serialize observable and multi-observable mutation while preserving synchronous delivery semantics.
• Add async observable scaffolding.
• Add Network listener, browser, advertiser, and session transport adapters.
• Add bounded Bonjour discovery metadata with UTF-8 byte-safe TXT records and local-self filtering.
• Add the public opt-in backend selector while preserving MultipeerConnectivity as the default.
• Add public optional availableMultipeerSession feature detection while retaining the existing multipeerSession API.
• Remove unused Network coordinator advertiser-observer plumbing.
• Incorporate secure peer-identity archiving, handshake-error propagation, and efficient frame decoding from the updated base.

Compatibility

Existing initializers and Multipeer-backed behavior remain source-compatible. Apps must explicitly choose .networkFramework; MultipeerConnectivity remains the default and fallback path. availableMultipeerSession allows callers to feature-detect the MC-specific session without triggering the existing non-optional accessor's unsupported-backend precondition.

Security and discovery

Discovery TXT entries are bounded by encoded UTF-8 byte length, reject malformed oversized records, and preserve valid scalar boundaries. Discovery metadata remains self-asserted and is not an authorization identity.

Verification

• swift test — 140 tests passed locally.
• iPhone 16 / iOS 18.3.1 Xcode tests — 140 tests passed locally.
• Added backend selection, optional-session, identity, handshake-failure, frame-decoder, TXT-boundary, multibyte, and truncated-self-filter coverage.
• Correctness and security reviews found no blockers.

Stack

• Parent: feat: introduce Network framework transport prototype #22
• Child: feat: secure, harden, and verify the Network backend #58
• Consolidates the former PRs Add Network migration CI baseline #23, Serialize event observer mutations #24, Add async observable scaffolding #25, Add Network transport adapters #27, and Add Network discovery metadata #28; their commits and branches remain preserved.

Stack update

• Rebases this PR stack onto the merged actor-backed Observable bridge from PR refactor: unify observables behind actor bridge #63.
• Removes the obsolete MultiObservable implementation from this branch's effective diff.
• Keeps event/listener behavior aligned with the async startup registration and synchronized responder listener registry now in the base branch.

Verification

• swift test passed after merging the updated base.
• swift build passed after merging the updated base.

Review-loop fixes

• Restacked terminal invalid/oversized frame handling from PR feat: introduce Network framework transport prototype #22.
• Removed superseded AsyncObservable/AsyncMultiObservable/SyncObservableBridge scaffolding at this first affected checkpoint so SwiftPM and Xcode builds independently use the PR refactor: unify observables behind actor bridge #63 actor-backed Observable architecture.
• Explicitly document that Network backend advertising ignores app-provided Multipeer discoveryInfo, reserves Bonjour TXT metadata for protocol identity, and reports nil discovery metadata; added an adapter expectation locking that behavior.

Post-fix verification: Swift and Xcode suites passed with 141 tests; the demo build passed. Correctness and security reviews found no blockers.

Review-loop pass 2

• Restacked the actor-owned AsyncStream Observable FIFO pump, packaging completion, and immediate handshake encoding cleanup.
• Added an explicit internal backend contract so injected transport managers report their backend accurately and expose no unavailable MCSession.
• Removed the unused coordinator discovery event route; NetworkPeerBrowserTransport is now the sole authoritative Network discovery path, with self-filtering coverage retained.

Post-fix verification: Swift and Xcode suites passed with 147 tests; the demo build passed. Correctness and security reviews found no blockers.

Handshake input hardening

Reject empty or over-63-byte UTF-8 display names from remote Network handshakes before Peer/MCPeerID construction. Invalid identities follow the existing idempotent cancellation path, never register, and emit no connected-peer event. Exact-boundary and malformed ASCII/multibyte cases are covered.

Post-fix verification: Swift suite passed with 151 tests; focused Xcode coordinator tests passed.

Identifier consistency hardening

Restacked PR #22 remote-handshake identifier bounds and made Bonjour discovery metadata reuse the same shared non-empty, 180-byte UTF-8 identifier validator. Empty/oversized handshakes reject before registration; exact-boundary multibyte values remain valid.

Post-fix verification: Swift and Xcode suites passed with 156 tests after one unrelated flaky listener test passed on full rerun.

Browser endpoint concurrency hardening

Serialize all Network browser endpoint registry reads, mutations, and clears. Endpoint lookup is copied before dialing and observer callbacks remain outside the lock. Added a 2,000-operation concurrent found/lost/invite/stop stress test with endpoint verification.

Post-fix Swift and Xcode suites passed with 157 tests.

Final loop status

The browser endpoint registry is now serialized across discovery, invite, and stop operations, with a 2,000-operation concurrency stress test. Final stack review found no remaining actionable issues.

Stack sync

Merged the updated base (NSLock synchronization centralization from #22 @ 66bb977) into this branch; auto-merged cleanly. Post-merge verification: swift test passed and the complete iPhone 16 / iOS 18.3.1 Xcode suite passed with 157 tests.

Note: this PR's Xcode Project Tests CI check failed twice on the previous head (c55e37c) while the same suite passes locally and on the restacked branches above (which contain this branch's code); treated as CI infrastructure flakiness with local verification per the loop's CI policy.

CI destination fix

The Xcode Project Tests workflow now resolves an available iPhone simulator UDID at run time instead of hard-coding name=iPhone 16. Runner images whose latest iOS runtime no longer includes an iPhone 16 device were fast-failing with "Unable to find a device matching the provided destination specifier"; the check is now runner-image agnostic. swift test re-passed with 157 tests after the change.

Xcode CI runner failure root cause

The Xcode Project Tests check fails on GitHub's macos-15 runners because the runner's device name is invalid for MultipeerConnectivity: constructing the local MCPeerID raises NSInvalidArgumentException (Sources/Peer.swift:91), terminating the test process partway through the run. This is runner-environment-specific — the full iPhone 16 / iOS 18.3.1 suite passes locally (157 tests), and the same suite passes on every branch above this one. The display-name sanitization that makes it runner-safe is intentionally layered in the next stack PR (#58). The simulator-destination fix on this branch remains (it eliminates a separate runner-image fast-fail); the remaining Xcode check failure on this PR is accepted per the loop's CI policy, with local verification standing in and the fix landing in #58 immediately above.