CORE-1 Collector Core 骨架与新版兼容门禁
结论
CORE-1 已建立独立的 perfowl_collector_core Python 包，冻结 pymobiledevice3 11.3.1 与 py-ios-device 研究版本，落实唯一 DTX owner、raw event、Adapter、SourcePlan、严格回放和新版 API 兼容探测契约。
当前 perfowl_collector.py、PyInstaller 默认入口和已打包 pymobiledevice3 4.21.3 均未修改，因此本批不会改变用户现有设备发现和采集链路。新版候选只完成 E1 源码 API 验证与 E2 自有代码测试；依赖安装、真实 import、打包与真机仍是后续门禁。
实现范围
| 模块 | 作用 | 本批边界 |
|---|---|---|
contracts.py |
CollectorAdapter、RawEventEnvelope、候选源、上游版本模型 |
只定义稳定契约，不采集真机 |
runtime.py |
DtxSessionOwner 生命周期与唯一入口 |
使用 fake backend 验证；CORE-2 才绑定 pmd3 |
pmd3_compat.py |
已安装环境 probe + 无依赖源码树 probe | 对冻结源码验证 9/9 API；runtime 尚未验证 |
source_policy.py |
硬门槛、加权评分、Session 固定 SourcePlan | 输出 candidate/unsupported，不切当前 UI 指标 |
replay.py |
严格 JSONL raw 回放 | sequence / monotonic 倒退 fail-closed |
pins.py + upstreams.lock.json |
上游版本、commit、发行物 hash、运行时角色 | py-ios-device 明确 runtime: false |
requirements-core-candidate.txt |
pmd3 11.3.1 顶层候选约束 |
不是完整 transitive lock，不进入当前打包 |
上游冻结事实
| 上游 | 版本 / commit | 发行物校验 | 角色 |
|---|---|---|---|
| pymobiledevice3 | 11.3.1 / e0dc322f… |
sdist、wheel SHA-256 已入 lock | 候选连接和 DTX 内核 |
| py-ios-device | source 2.4.26 / 67b36f0…；PyPI 2.4.25 |
PyPI sdist、wheel SHA-256 已入 lock | 研究源，不进入产品运行时 |
唯一 DTX owner 契约
DtxSessionOwner 状态固定为：
new → open → closing → closed约束包括：
- 未 open 时不能开 channel、调用 selector 或订阅事件；
- 同一个
adapterID不能重复 claim； - 所有 channel、invoke 和 subscribe 经过 owner；
- close 幂等，但 closed Session 不能重新 open；
- 本批 backend 是 Protocol / fake，不直接操作 socket。
CORE-2 的 pymobiledevice3 backend 必须在这个边界后面实现，Adapter 不获得裸 DTXConnection。
RawEventEnvelope v1
每条 raw fact 至少携带：
schema / sequence / eventType
service / channel / selector
sourceID / adapterID / adapterVersion
upstreamVersion / upstreamCommit
hostReceiveMonotonicNs
quality / decodeStatus
droppedEventCount / reconnectGeneration
rawPayload设备 mach time、时间基、目标 PID/generation、身份状态、scope 与 raw unit 为可选字段；缺失就不写，不生成 0。本批 Fixture 显式覆盖空 rawPayload + quality=missing，往返序列化后仍保持缺失语义。
SourcePolicy 公式
候选源必须先通过六项硬门槛：身份闭环、scope/unit 已证、缺值保真、稳定性、目标 iOS 覆盖、raw 可回放。
通过后才计算：
SourceScore =
correctness × 0.35
+ attribution × 0.20
+ compatibility × 0.15
+ stability × 0.10
+ overhead × 0.10
+ completeness × 0.05
+ maintenance × 0.05- 每维输入范围
0...100，缺维、非有限值或越界直接拒绝； - 分数保留四位小数；
- 同分时按
pmd3-wrapper → perfowl-adapter → custom-decoder； - 无候选通过硬门槛时输出
unsupported； - 选中结果只形成不可变
SourcePlan，不允许采集中途静默切源。
这是采集源选择公式，不改变 CPU、FPS、Network 等现有指标公式。
新版 API 兼容门禁
源码 probe 不导入第三方依赖，直接检查冻结 v11.3.1 源码树。结果：
| Capability | 必需符号 | E1 结果 |
|---|---|---|
| DTX Provider | DvtProvider，构造参数含 dtx |
通过 |
| Sysmon | Sysmontap |
通过 |
| Graphics | Graphics |
通过 |
| Device Network | NetworkMonitor |
通过 |
| Energy | EnergyMonitor |
通过 |
| CoreProfile | CoreProfileSessionTap |
通过 |
| Process Control | ProcessControl |
通过 |
| Device Info | DeviceInfo |
通过 |
| Generic Tap | TapChannel |
通过 |
结果为 9/9 E1 API surface ready。它证明候选源码具备预期入口，不证明依赖可安装、对象可建链或真机数据正确。
另有 runtime probe：只有已安装版本精确等于 11.3.1 且 9 个模块均可导入时才输出 ready=true。当前产品环境仍是 4.21.3，所以新版 runtime 门禁保持关闭。
验证结果
| 验证 | 结果 | 证据等级 |
|---|---|---|
| Python 3.12 全量 Sidecar | 38/38 | E2 |
| Apple Python 3.9 全量 Sidecar | 38/38 | E2 |
| Swift 全量测试 | 62/62 | E2 |
pmd3 v11.3.1 冻结源码 API probe |
9/9 | E1 |
| VitePress | 本批文档构建通过 | E2 |
pmd3 11.3.1 依赖安装 / import |
未完成 | 门禁开放 |
| Collector / App 新版打包 | 未进行 | 门禁开放 |
| 真机连接与采集 | 未进行 | 门禁开放 |
未修改事实
MacApp/Sidecar/perfowl_collector.py未修改；MacApp/scripts/build-sidecar.sh未切换入口；MacApp/scripts/build-app.sh未改变打包来源；- 当前
4.21.3回滚链未删除； - UI、Registry 和 Session 指标没有新增或改名；
- py-ios-device 没有加入 requirements 或产品运行时。
下一批准边界
下一批 CORE-2 才会：
- 在隔离构建环境解析并锁定 pmd3
11.3.1完整依赖； - 实现 pymobiledevice3 async backend；
- 让 Sysmon、Graphics、Device Network Adapter 共享一个
DvtProvider / DTXConnection； - 增加取消、timeout、backpressure、关闭顺序和 reconnect generation；
- 保持 feature flag 与
4.21.3回滚 Adapter； - 先离线和构建验证，再单独进入真机 CORE-3。