feat(discovery): route production dialing through peer directory

[mkdir700]

完成 #34 的第一个发现切片：生产拨号统一从 Application 的发现负责人获取候选，mDNS 持续收集、云端按需查询。同一端点的不同来源独立更新和失效，云端缓慢或失败不阻塞有效本地候选。

实现与替换

• 新增 provider、候选目录和发现调度；不透明传输身份与逻辑 DeviceId 分离，目录按来源限容并执行 TTL 清理。
• 替换节点直接挂载 DNS/mDNS 查询和会话直接订阅 mDNS 的旧路径，接入既有 iroh 生产 address lookup。Space 切换沿用网络候选，身份映射与授权使用当前会话。
• 陌生端点仅作为内部未绑定候选，不自动配对或拨号；不新增附近设备列表。LAN-only 不装配云端解析或发布。
• 修复 vendored mDNS 的旧地址缓存、主动 resolve 抑制订阅、晚订阅快照及读取缓存重新续期问题；节点关闭取消并等待发现任务，停止所有克隆共用的 mDNS 服务。
• 删除镜像生产 builder 的旧测试，改为实际 NodeBuilder 验证；保留现有传输、协议、Relay 路径选择与业务重试负责人。
• 更新发现设计与完成计划；目录仅存内存，不新增持久化格式或稳定 Engine API。

验证

• 74 项定向 nextest 通过；补齐 TTL 回归后 16 项复验通过，两次筛选存在重叠。
• mDNS 回归先复现失败，再验证修复；覆盖订阅、地址更新/快照、过期、取消、关闭及 Space 切换。
• 现有独立进程/Linux namespace harness（每场景一次）：真实三节点配对、E02 双向文本/文件、E04 网络恢复提示、修改前后宿主混合 E02，以及 E10 直连期间 Relay 中断和屏蔽直连后的 Relay 恢复均通过。
• Relay 就绪后 348 ms 恢复在线、482 ms 完成双向传输，未重建整个会话。所有网络证据的清理与明文落盘检查通过。
• cargo metadata --locked --format-version 1、cargo check --workspace --all-targets --locked、cargo fmt --all -- --check、Rust 风格、仓库架构及 git diff --check 全部通过。全工作区保留两处既有测试的未使用导入警告。

范围与未执行项

公网 Cloud 服务成功解析、物理 Desktop/Mobile 验收、已发布旧版本互通与发布产物验收均跳过。混合版本仅验证本次修改前的 007a5a20 与本次实现；网络实验使用本地 Relay。构建 SHA、重放命令和详细结果见完成计划，本地证据保留在 target/discovery-evidence/，未提交生成产物。

Connection/ConnectionPool 抽象与协议迁移属于后续切片。本 PR 仅关联 #34，不关闭整个 issue。

Summary by CodeRabbit

• New Features
  • Added device discovery through local-network mDNS and, when relays are enabled, cloud lookups.
  • Discovery results include connection candidates that expire over time, and updates are shared with active discovery queries.
  • Discovery now shuts down with the network node. Finding a device does not automatically connect, pair, or grant access to it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7b9d874d-d2ee-4c11-a655-242204879940

---

📥 Commits

Reviewing files that changed from the base of the PR and between 007a5a2 and 9fe8e27.

---

📒 Files selected for processing (29)

• crates/uc-application/src/deps.rs
• crates/uc-application/src/discovery/candidate.rs
• crates/uc-application/src/discovery/directory.rs
• crates/uc-application/src/discovery/error.rs
• crates/uc-application/src/discovery/manager.rs
• crates/uc-application/src/discovery/mod.rs
• crates/uc-application/src/discovery/provider.rs
• crates/uc-application/src/discovery/tests.rs
• crates/uc-application/src/lib.rs
• crates/uc-infra-p2p/src/network/iroh/discovery/cloud.rs
• crates/uc-infra-p2p/src/network/iroh/discovery/lookup.rs
• crates/uc-infra-p2p/src/network/iroh/discovery/mdns.rs
• crates/uc-infra-p2p/src/network/iroh/discovery/mod.rs
• crates/uc-infra-p2p/src/network/iroh/discovery/runtime.rs
• crates/uc-infra-p2p/src/network/iroh/discovery/tests.rs
• crates/uc-infra-p2p/src/network/iroh/mod.rs
• crates/uc-infra-p2p/src/network/iroh/node.rs
• crates/uc-infra-p2p/src/network/iroh/node/discovery_tests.rs
• crates/uc-infra-p2p/src/network/iroh/node/shutdown.rs
• crates/uc-infra-p2p/tests/lan_only_relay_mode.rs
• crates/uc-infra-p2p/tests/mdns_discovery_contract.rs
• crates/uc-observability-contract/src/diagnostics/mod.rs
• docs/architecture/architecture-bible.md
• docs/design-docs/index.md
• docs/design-docs/observability.md
• docs/design-docs/peer-discovery.md
• docs/exec-plans/completed/2026-10-11-peer-discovery-slice.md
• third_party/iroh-mdns-address-lookup/UNICLIPBOARD_PATCH.md
• third_party/iroh-mdns-address-lookup/src/lib.rs

---

💤 Files with no reviewable changes (1)

• crates/uc-infra-p2p/tests/lan_only_relay_mode.rs

---

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The change adds application-level peer discovery with a bounded, in-memory directory and provider manager. It integrates mDNS and cloud lookup with Iroh, gives the node ownership of discovery startup and shutdown, and adds tests and design records for these behaviors.

Changes

Peer discovery

Layer / File(s)	Summary
Discovery contracts and directory crates/uc-application/src/discovery/*, crates/uc-application/src/deps.rs, crates/uc-application/src/lib.rs	The application crate adds discovery IDs, observations, events, candidates, provider and error contracts, and public re-exports. PeerDirectory validates and expires observations, stores them separately by provider, and enforces per-provider capacity.
Provider coordination and resolution crates/uc-application/src/discovery/manager.rs, crates/uc-application/src/discovery/tests.rs	DiscoveryManager returns cached candidates, processes provider streams, broadcasts changed peers, removes failed sources, and clears the directory on shutdown. Tests cover source behavior, failures, and query cancellation.
mDNS observations and lifecycle third_party/iroh-mdns-address-lookup/src/lib.rs, third_party/iroh-mdns-address-lookup/UNICLIPBOARD_PATCH.md, crates/uc-infra-p2p/tests/mdns_discovery_contract.rs	The mDNS lookup broadcasts updates during active resolution, provides cached observations to new subscribers, records observation timestamps, and adds shutdown methods. Contract tests cover updates, snapshots, and subscription closure.
Iroh discovery providers and lookup crates/uc-infra-p2p/src/network/iroh/discovery/*, crates/uc-infra-p2p/src/network/iroh/mod.rs	Iroh adapters map mDNS and cloud lookup results to discovery observations. The directory-backed lookup converts candidates to Iroh items and validates peer identity against decoded locators. Tests cover expiry, identity validation, and connectivity.
Node integration and lifecycle crates/uc-infra-p2p/src/network/iroh/node.rs, crates/uc-infra-p2p/src/network/iroh/node/*, crates/uc-infra-p2p/src/network/iroh/node/shutdown.rs, crates/uc-infra-p2p/tests/lan_only_relay_mode.rs, crates/uc-observability-contract/src/diagnostics/mod.rs, docs/architecture/architecture-bible.md, docs/design-docs/*, docs/exec-plans/completed/2026-10-11-peer-discovery-slice.md	The node uses discovery-manager changes for connection hints and owns the discovery runtime. Cloud discovery is enabled when relays are enabled, and node shutdown stops the runtime. The change adds a peer-discovery diagnostic kind and records design and validation details; it also removes earlier address-lookup service-count tests.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant IrohNode
  participant DirectoryAddressLookup
  participant DiscoveryManager
  participant PeerDirectory
  participant MdnsDiscoveryProvider
  participant CloudDiscoveryProvider
  IrohNode->>DirectoryAddressLookup: resolve(peer)
  DirectoryAddressLookup->>DiscoveryManager: resolve(peer)
  DiscoveryManager->>PeerDirectory: candidates(peer, now)
  PeerDirectory-->>DiscoveryManager: unexpired candidates
  DiscoveryManager->>MdnsDiscoveryProvider: resolve(peer)
  DiscoveryManager->>CloudDiscoveryProvider: resolve(peer)
  MdnsDiscoveryProvider-->>DiscoveryManager: discovery stream
  CloudDiscoveryProvider-->>DiscoveryManager: discovery stream
  DiscoveryManager-->>DirectoryAddressLookup: candidates or errors
  DirectoryAddressLookup-->>IrohNode: Iroh lookup items or errors

Loading

---

Merge Risk: ⚪ Minimal · up to 9fe8e

This change moves peer discovery into an application-level directory and manager, wired into the Iroh node's startup and shutdown. No concrete merge-blocking defect was identified in the supplied material. Real cloud resolution and physical-device behavior were not validated, but that is routine follow-up rather than a demonstrated risk.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 37.66% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 77 functions across 22 files. (6 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly summarizes the main change: routing production dialing through the peer directory for discovery.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 37.66% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 77 functions across 22 files. (6 skipped: 6 unsupported.)

---

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}