外观
Free Memory（设备完全空闲物理页）
当前共享采集源（2026-10-07 G84）：产品 SysmontapRawAdapter._make_stream 先用同一个 pymobiledevice3 原生 DeviceInfo 查询时钟与支持列，再用原生 Sysmontap 构造器建立完整14消费者固定依赖闭包（11进程列、3系统列）；默认 intervalMs=500、ur=500 ms、sampleInterval=500000000 ns，保留CPU元数据与原生时钟。必需列缺失、非法类型或重复时明确失败，不以减少指标、补值或旧值续点降级。此为采集配置修复，不改变本页数值公式、scope、单位、质量/候选标签与独立误差门；完整54项与正式五轮仍待验，源码/安装验证不等于本指标数值校准。方案与验证。
作用域属性：[设备级 · 整机环境]（Device Scope ） Memory Contract：memory-contract.v2
1. 定义与业务价值
Free Memory 是设备当前完全空闲的物理页容量，用于观察整机内存环境。它有环境诊断价值，但不等于 Available Memory（见 Available Memory 第 12 节）。
2. metricID / scope / unit / source
| 字段 | 值 |
|---|---|
| metricID | ios.device.memory.free |
| scope | device |
| unit | bytes |
| source | dvt.sysmontap |
| sourceKey | System.vmFreeCount * VMPageSizeBytes |
| definitionVersion | vm-free-pages.v1 |
取自当前 Registry 。
3. iOS 系统原理
vmFreeCount 是内核维护的完全空闲物理页计数，是虚拟内存管理中最基础的空闲资源统计，但不包含系统认为"可以较快回收投入使用"的 external/purgeable 等可回收页（那部分属于 Available Memory 的构成）。
4. 系统服务 / 通信通道 / 采集命令与实现
通道：com.apple.instruments.server.services.sysmontap（DTX ）。采集：pymobiledevice3 原生 Sysmontap(provider, process_attributes, system_attributes, interval_ms=intervalMs) 返回的 System 级快照字段；解析实现于 MacApp/Sidecar/perfowl_collector_core/metric_engine.py::MetricEngine._system_metrics（第 302~314 行）。页大小来自 SysmontapRawAdapter._payload（MacApp/Sidecar/perfowl_collector_core/adapters.py）在检测到 vmFreeCount 字段时注入的 VMPageSizeBytes = 16384，标签为 ios15-plus-arm64-16k.candidate.v1。
5. 原始字段与字段语义
System.vmFreeCount：内核上报的完全空闲物理页数量；VMPageSizeBytes：当前 iOS 15+ arm64 路径上使用的带来源标签的候选架构约束值（16 KiB），不是本次 payload 的设备实测字段。
6. 精确公式
text
FreeMemoryBytes = vmFreeCount × VMPageSizeBytes来源：metric_engine.py 第 302~314 行。若未来获得可验证的设备内核 page size，应升级 definitionVersion 与来源标签，而不是直接替换数值假设。
7. Clock / Window / Freshness
Gauge 类型，随同一 sysmontap 系统快照产出，与其它 device 级字段（TotalCPU、Per-Core）共享同一窗口。
8. Baseline / Reset / Discontinuity
无 counter 语义，无前值依赖。
9. Quality：valid / candidate / missing
vmFreeCount 非负且 page_size 有效 → candidate；任一输入缺失或无效 → missing，不补 0。
10. 合法 0 的条件
理论上可以合法为 0（设备完全没有空闲页的极端场景），但极为罕见，出现时应结合其他内存指标交叉确认而非默认为采集异常。
11. 当前证据、校准与平台覆盖
vm-free-pages.v1 随 memory-contract.v2（2026-09-16 方案）与 CORE-8 确定性引擎落地；16 KiB page size 目前仍是候选架构约束值，不是当前 payload 的设备实测证据，这一状态尚未关闭。
12. 如何分析：能得到什么结论，不能得到什么结论
能得到：设备此刻完全空闲的物理页容量，可作为整机内存环境的背景参考。
不能得到：
- Free 很低不代表"整机只剩这么多能用"，系统可能还有大量可回收的 file-backed / purgeable 页尚未计入；
- 不能用 Free 替代 Available——两者回答不同问题（详见 Available Memory）；
- 不能把设备级 Free 直接归因为目标 App 的可用内存预算。
13. 常见误区
- 把 Free 当作 Available 的同义词（历史遗留误区，见第 14 节）；
- 把 16 KiB page size 当作当前 payload 实测得到的设备真实值。
14. Legacy / 历史实现
旧版 Perfowl 曾把 vmFreeCount × pageSize 的计算结果直接命名为 Available Memory——这是历史命名错误：该公式只计算 free page list，不包含 external/purgeable 等可回收资源。memory-contract.v2 起正式更名为 Free Memory（ios.device.memory.free），并把真正的 XNU memorystatus 语义候选重建交给独立的 Available Memory 指标。历史 Session 中的 availableMemoryBytes 字段做只读迁移：memoryContractVersion == memory-contract.v2 之前的 Session，其 availableMemoryBytes 按 legacy-free-mislabeled 质量标签解释为 Free Memory，不得被新版误读为新 Available；历史文件本身不回改。
15. 版本历史与来源批次
本页由 site/knowledge/metrics/memory-metrics.md v5（2026-09-15）拆分而来，历史沿革见 Memory Contract 技术演进与实验。
| 版本 | 日期 | 修订要点 |
|---|---|---|
| v1（本页） | 2026-09-18 | 从 memory-metrics.md 拆出，成为 Free Memory 独立 Canonical；补充精确代码引用与历史 Available 迁移规则。 |
2026-10-05 G35 · 页大小独立观察（限定原设备A）
旧真机自有Fixture的181条host_page_size调用均返回status0/16384B，并与原封存清单和reference-manifest SHA一致；这关闭了该设备该次参考中16KiB常数是否有独立API观察这一窄项。产品的VMPageSizeBytes仍是adapter附入的候选约束标签，并未变为每次设备实测；其它设备/代际的页大小未证明。
181条self参考的Free与free+external+purgeable乘页大小算术自洽，不是产品Free/Available与独立内核值的动态同窗对照；secluded与完整Available定义仍缺参考。新默认关闭时钟参考仅E2准备，未回写旧Session或缩54项分母，不能把该窄观察当整项准确性/五轮100%通过。G35方法与证据边界。
| 版本 | 日期 | 修订 |
|---|---|---|
| 公式不变，参考观察增量 | 2026-10-05 | 设备A旧181条独立API页大小均16KiB；其它设备、动态数值与完整Available门不关闭。 |
采集源版本更新 · 2026-10-07
G84将SDK全列factory改为固定共享11+3列、输出与采样节拍一致；原生服务/DTX通道不变，支持列仍由SDK查询，传输及指标转换为Perfowl适配层，SDK来源和自研计算分开。初missing、counter warmup/reset、VM近似质量等原边界保留，不外推其他设备/场景持续100%。来源批次。
当前口径与阶段验收更新 · 2026-10-16
Free在设备A、自有AppA、内部175/Lab90.21.3固定五轮限定范围E4阶段验收通过。复核结果1200/1200来源可用、600/600完整槽、1186普通、14参考过宽未评估、0严重与来源违规，最大间隙0.5秒；未评估不当正常。采用排除明显异常及覆盖门，不是物理精度100%或全设备通用保证。完整验收。
原始语义、候选公式与在线发表
上文“完全空闲”是Registry目标定义；私有System.vmFreeCount与公开HOST_VM_INFO计数的精确内核同义性尚未独立确证。当前产品仍为vmFreeCount×16384 bytes，页大小标签ios15-plus-arm64-16k.candidate.v1，quality保持candidate。原生参考(free−speculative)×实测page只用于同窗异常筛查，不替代产品公式，不改名为Available。参考来自自有工具Mach API；产品仍通过pymobiledevice3 Sysmontap与Perfowl适配层获取，无新传输或注入。
v2在线策略device-free-source-once.v2：primary/supplemental各有容量6的有界保管；单调原生end/adapter与持久化序列分别校验；同end跨角色重复只发布一次，冲突/身份或来源变化保守拒绝。合法新原始0可发布0；来源沉默、已消费/过期、配置不合法均空值，不重复旧数。窗口TTL沿原3×实际声明采样周期，Core GUI显式500ms、Session计划0.5s；legacy/独立CLI旧默认不改。未带策略的历史回放保留兼容，v2启动后不降级复用v1旧队列。
验收中可复用的方法与坑点
- 跨角色重复输入与重复发表分别核对：同原始end且逐字段相同才可过滤；冲突不能用“去重”掩盖。Raw保留输入，发表账本保留源序列与持久化序列。
- 原生参考±1s自然括号太宽或断档，结果为未评估，不因产品落在大区间就判准确；用固定240机会/120双点槽保留完整分母。
- 出厂采集周期与实际runtime绑定，不能只改Session元数据；direct与prewarm、Core与legacy分别验证，同一Supervisor只构造一次。
- 验收过的安装包不等于main源码完整：逐模块字节码及接线核同、干净源码回归、原E4版本分别登记。不要借此混入其他未验收改动。
| 版本 | 日期 | 修订与来源 |
|---|---|---|
| 在线保管v2／公式不变 | 2026-10-16 | Free五轮限定E4验收、候选语义与14未评估保留；主线整合。 |
2026-10-17 · 已验源码主线对应与交付边界
Free两角色来源保管、策略与GUI真实500ms周期接线及必要依赖已在main a1757da；原五轮证据限定内部175/Lab90.21.3，相关六模块与安装177代码对象核同，不把它写成177新增五轮。原1200可用/600完整槽、1186普通/14未评估及0严重/来源违规不变。完整后端的一项继承wall性能门仍开放，签名177保留；GitHub及知识网站已核，GitLab连接失败仅一次，整体同步partial。无公式或质量升级。主线对应与诊断。