acprof 0.3.0__py3-none-any.whl

acprof/__init__.py

@@ -0,0 +1,3 @@
+"""AC-Prof package."""
+
+__version__ = "0.3.0"

acprof/__main__.py

@@ -0,0 +1,5 @@
+"""Run the installed AC-Prof commands with python -m acprof."""
+from acprof.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

acprof/_bundle/.dockerignore

@@ -0,0 +1,20 @@
+# 构建只读取受版本控制的代码、Dockerfile 和依赖输入。
+.git
+.venv
+.release-venv
+dist
+build
+tests/
+docs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+.env*
+.agents
+.codex
+internal-testing
+results*
+result-past
+**/__pycache__
+**/*.pyc

acprof/_bundle/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

acprof/_bundle/NOTICE

@@ -0,0 +1,43 @@
+AC-Prof
+https://github.com/kainam15/AC-Prof
+
+Project origin and attribution
+------------------------------
+AC-Prof is part of the DOR project of the DISTINT group at Jinan University:
+https://github.com/wingter562/DISTINT_open_data
+
+The original project definition credits Dr. Wentai Wu (Jinan University),
+with primary contribution by Dr. Shenghai Li (South China University of
+Technology), and lists these contributors:
+  Wentai Wu, JNU
+  Shenghai Li, SCUT
+  Qinan Wu, JNU
+  Kaizhe Song, JNU
+  Yukai Wang, JNU
+
+The attribution above follows the original AC-Prof project definition.
+This repository continues that project with the current Python package,
+runtime profiles, measurement protocol, CLI and Textual interface. Source
+history records the subsequent changes and contributors.
+Project code is licensed under Apache-2.0; see LICENSE.
+
+Bundled third-party material
+---------------------------
+assets/audio/librispeech-clean-test-en-30s/audio.wav is derived from
+LibriSpeech, prepared by Vassil Panayotov with assistance from Daniel Povey.
+Source: https://www.openslr.org/12
+Mirror: https://huggingface.co/datasets/openslr/librispeech_asr
+Dataset revision: 71cacbfb7e2354c4226d01e70d77d5fca3d04ba1
+License: Creative Commons Attribution 4.0 International (CC-BY-4.0).
+See licenses/CC-BY-4.0.txt and https://creativecommons.org/licenses/by/4.0/.
+
+AC-Prof concatenated clean/test recordings 6930-75918-0001,
+6930-75918-0002 and 6930-75918-0003, then retained the first 30 seconds as
+16 kHz mono PCM16 WAV. It did not normalize, resample, apply gain or trim
+silence. The source identities, hashes and transformation details are in
+assets/audio/librispeech-clean-test-en-30s/source.json.
+The audio retains CC-BY-4.0 and is not relicensed under Apache-2.0.
+
+Downloaded model code, weights, external datasets and separately installed
+dependencies retain their respective licenses. Their inclusion or use does
+not imply endorsement by their authors or by the original project team.

acprof/_bundle/acprof/__init__.py

@@ -0,0 +1,3 @@
+"""AC-Prof package."""
+
+__version__ = "0.3.0"

acprof/_bundle/acprof/__main__.py

@@ -0,0 +1,5 @@
+"""Run the installed AC-Prof commands with python -m acprof."""
+from acprof.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

acprof/_bundle/acprof/analysis/__init__.py

@@ -0,0 +1 @@
+"""AC-Prof analysis."""

acprof/_bundle/acprof/analysis/audit.py

@@ -0,0 +1,276 @@
+"""只读结果审计；保持历史字段和不可用原因，不回填测量值。"""
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+import math
+from collections import Counter
+from pathlib import Path
+
+from acprof.artifact_layout import ArtifactLayout
+from acprof.artifacts import read_json_object
+from acprof.capabilities import collection_outcomes
+from acprof.failures import Failure
+from acprof.metric_registry import METRICS, NUMERIC_FIELDS
+from acprof.platform import native_only_metric, recorded_identity
+from acprof.quality import read_quality, summarize_quality
+from acprof.result_csv import (
+    ResultCsvSnapshot,
+    expected_measurements,
+    measurement_key,
+    read_result_csv_snapshot,
+    result_csv_snapshot_unchanged,
+)
+
+MISSING = {"", "nan", "none", "null", "n/a"}
+
+
+def number(value):
+    try:
+        result = float(value)
+        return result if math.isfinite(result) else None
+    except (ValueError, TypeError, OverflowError):
+        return None
+
+
+def missing_reason(field: str, row: dict, metadata: dict) -> str:
+    if field not in row:
+        return "not_recorded"
+    metric = METRICS[field]
+    if recorded_identity(metadata)["environment_class"] == "wsl2" and native_only_metric(metric):
+        return "unavailable_on_wsl2"
+    if metric.applicability in {"gpu", "gpu_idle_debug"} and row.get("gpu_mode") == "off":
+        return "not_applicable"
+    if metric.applicability == "cpu" and row.get("gpu_mode") == "on":
+        return "not_applicable"
+    if str(row.get("status", "")).strip().lower() == "error":
+        return "measurement_failed"
+    if metric.tool:
+        suffix = "torch_profiler_eager" if metric.tool == "torch" else metric.tool
+        error = str(row.get(f"compute_profile_error_{suffix}", "")).strip()
+        if error.lower() not in MISSING:
+            return "profiler_reported_error"
+        key = "compute_profile_tools" if metric.tool in {"torch", "ncu"} else "execution_profile_tools"
+        enabled = metadata.get(key)
+        if isinstance(enabled, str):
+            try:
+                enabled = json.loads(enabled)
+            except ValueError:
+                enabled = enabled.split(",")
+        if isinstance(enabled, list) and not any(metric.tool in str(tool) for tool in enabled):
+            return "tool_not_enabled"
+    return "unavailable_unspecified"
+
+
+def _formula_checks(row: dict) -> dict[str, float]:
+    """仅检查可由同一行确定的关系，不重建 RAPL 分段归因或补猜缺失来源。"""
+    values = {name: number(value) for name, value in row.items()}
+    expected = {}
+    cpu = values.get("vcpu_energy_eff_j")
+    gpu = values.get("gpu_energy_eff_j") if row.get("gpu_mode") == "on" else 0.0
+    if cpu is not None and cpu >= 0 and gpu is not None and gpu >= 0:
+        expected["container_attributed_energy_eff_j"] = cpu + gpu
+    request = values.get("packet_request_wire_bytes_per_request")
+    response = values.get("packet_response_wire_bytes_per_request")
+    if request is not None and response is not None:
+        expected["packet_total_wire_bytes_per_request"] = request + response
+    total = values.get("packet_total_wire_bytes_per_request")
+    payload = values.get("packet_tcp_payload_bytes_per_request")
+    if total is not None and payload is not None:
+        expected["packet_protocol_overhead_bytes_per_request"] = total - payload
+        if total > 0:
+            expected["packet_protocol_overhead_ratio"] = (total - payload) / total
+    return expected
+
+
+def _check_workload_counts(row: dict) -> None:
+    raw = row.get("workload_contract", "")
+    if str(raw).strip().lower() in MISSING:
+        return
+    summary = json.loads(raw)
+    if not isinstance(summary, dict) or summary.get("schema_version") != 1:
+        raise ValueError("不支持的 workload_contract 摘要格式")
+    total = summary.get("request_count")
+    variants = summary.get("variants")
+    if type(total) is not int or total < 0 or not isinstance(variants, list):
+        raise ValueError("workload_contract 缺少合法 request_count/variants")
+    counts = [item.get("count") if isinstance(item, dict) else None for item in variants]
+    valid_counts = [count for count in counts if type(count) is int and count > 0]
+    if len(valid_counts) != len(counts) or sum(valid_counts) != total:
+        raise ValueError("workload_contract 的 variants 计数与 request_count 不一致")
+    completed = number(row.get("repeat_in_window"))
+    if completed is not None and completed != total:
+        raise ValueError("workload_contract.request_count 与 repeat_in_window 不一致")
+
+
+def audit_result(source: str | Path, *, result_snapshot: ResultCsvSnapshot | None = None,
+                 verify_result_snapshot: bool = True) -> dict:
+    path = Path(source)
+    if path.is_dir():
+        path /= "result_layers.json"
+    report = {**summarize_quality(None), "schema_version": 1, "result_csv": str(path.resolve()),
+              "valid": True, "issues": [], "missing_metrics": {},
+              "counts": {"rows": 0, "formal_ok": 0, "warmup": 0, "warn": 0, "error": 0},
+              "completion": "unknown", "measurement_status": "unknown", "run_status": "unknown", "coverage": None}
+
+    def issue(code, message, *, severity="error", **detail):
+        report["issues"].append({"code": code, "message": str(message), "severity": severity, **detail})
+        if severity == "error":
+            report["valid"] = False
+
+    def read_json(name):
+        try:
+            artifact = layout.path(name)
+            if not artifact.exists():
+                return {}
+            return read_json_object(artifact, label=name)
+        except (ValueError, OSError) as error:
+            issue("invalid_metadata", f"{name}: {error}")
+            return {}
+
+    def recorded_failure(name, location, value):
+        try:
+            if not isinstance(value, dict):
+                raise ValueError("typed failure must be an object")
+            failure = Failure(**value)
+            string_fields = (failure.stage, failure.detail, failure.device, failure.runtime_profile,
+                             failure.exception_type)
+            if (not failure.stage or not failure.detail or any(not isinstance(item, str) for item in string_fields)
+                    or not isinstance(failure.evidence, dict)):
+                raise ValueError("typed failure fields have invalid types")
+            return failure.to_dict()
+        except (TypeError, ValueError) as error:
+            issue("invalid_metadata", f"{name} {location}: {error}")
+            return None
+
+    try:
+        layout = ArtifactLayout.from_csv(path)
+    except (ValueError, OSError) as error:
+        issue("invalid_layout", error)
+        return report
+    report["layout_version"] = layout.layout_version
+    metadata = read_json("static_meta.json")
+    validation = read_json("runtime_validation.json")
+    resolution = read_json("model_resolution.json")
+    report["failures"] = []
+    devices = validation.get("devices", {})
+    if not isinstance(devices, dict):
+        issue("invalid_metadata", "runtime_validation.json devices: expected an object")
+    else:
+        for device, item in devices.items():
+            if not isinstance(item, dict):
+                issue("invalid_metadata", f"runtime_validation.json devices.{device}: expected an object")
+            elif item.get("failure") is not None:
+                failure = recorded_failure("runtime_validation.json", f"devices.{device}.failure", item["failure"])
+                if failure is not None:
+                    report["failures"].append(failure)
+    recorded = read_json("runtime_failures.json").get("failures", [])
+    if not isinstance(recorded, list):
+        issue("invalid_metadata", "runtime_failures.json failures: expected a list")
+    else:
+        for index, value in enumerate(recorded):
+            failure = recorded_failure("runtime_failures.json", f"failures[{index}]", value)
+            if failure is not None:
+                report["failures"].append(failure)
+    if resolution.get("failure") is not None:
+        failure = recorded_failure("model_resolution.json", "failure", resolution["failure"])
+        if failure is not None:
+            report["failures"].append(failure)
+    report.update(read_quality(path))
+    for failure in report["failures"]:
+        issue(failure["reason_code"], failure["detail"], failure=failure)
+    for check in report["quality_checks"]:
+        issue(check["code"], check["detail"], severity=check["severity"], quality_check=check)
+    report.update(recorded_identity(metadata))
+    state = read_json("run_state.json")
+    if state:
+        report["run_status"] = state.get("status")
+        report["run_id"] = state.get("run_id")
+        report["completion"] = "complete" if state.get("status") == "complete" else "incomplete"
+    try:
+        snapshot = result_snapshot or read_result_csv_snapshot(path)
+        if snapshot.path != path.resolve():
+            raise ValueError("result CSV snapshot belongs to a different path")
+        fields, rows = snapshot.fields, snapshot.rows
+        report["result_sha256"] = snapshot.sha256
+        if verify_result_snapshot and not result_csv_snapshot_unchanged(snapshot):
+            issue("changing_snapshot", "读取期间 CSV 发生变化，请采集结束后重新审计")
+    except (ValueError, OSError, csv.Error) as error:
+        issue("invalid_csv", error)
+        return report
+    report["counts"]["rows"] = len(rows)
+    if "environment_class" not in fields:
+        issue("missing_environment_class", "结果缺少 environment_class 环境身份列")
+    environments = {row.get("environment_class", "unknown") for row in rows}
+    report["row_environment_classes"] = sorted(environments)
+    if len(environments) > 1 or any(value not in {"unknown", report["environment_class"]}
+                                  for value in environments):
+        issue("environment_mismatch", "CSV 与元数据环境身份不一致，或包含混合环境结果")
+    if report["environment_class"] == "unknown":
+        issue("unknown_environment", "环境身份 unknown；不能作为 Native Linux baseline", severity="warning")
+    report["execution"] = collection_outcomes(rows)
+    report["unknown_columns"] = [name for name in fields if name not in METRICS]
+    report["missing_columns"] = [name for name in METRICS if name not in fields]
+    expected_hash = metadata.get("input_scale_plan_sha256")
+    if expected_hash and str(expected_hash).lower() not in MISSING:
+        try:
+            plan = layout.path("input_scale_plan.json")
+            if not plan.is_file() or hashlib.sha256(plan.read_bytes()).hexdigest() != expected_hash:
+                issue("input_plan_hash", "输入计划与 static_meta.json 中的 SHA256 不一致")
+        except (OSError, ValueError) as error:
+            issue("input_plan_hash", error)
+    if state.get("runtime"):
+        try:
+            options = state["options"]
+            expected = expected_measurements(
+                [int(value) for value in options["cpus"].split(",")],
+                [int(value) for value in options["mems"].split(",")], options["gpus"].split(","),
+                state["runtime"]["planned"]["scales"], options["warmup"], options["repeat"],
+            )
+            actual = {measurement_key(row) for row in rows}
+            report["coverage"] = {"expected": len(expected), "actual": len(actual),
+                                  "missing": len(expected - actual), "unexpected": len(actual - expected)}
+            if expected != actual:
+                issue("plan_coverage", "结果行与原实验计划不完全一致")
+        except (ValueError, KeyError, TypeError, AttributeError) as error:
+            issue("invalid_run_state", error)
+    missing: dict[str, Counter[str]] = {}
+    for index, row in enumerate(rows, 2):
+        status = row.get("status", "").strip().lower()
+        warmup = number(row["warmup"]) == 1
+        report["counts"]["warmup"] += warmup
+        if status not in {"ok", "warn", "error"}:
+            issue("invalid_status", "status 应为 ok、warn 或 error", row=index)
+        if status in {"warn", "error"}:
+            report["counts"][status] += 1
+        formal = status == "ok" and not warmup
+        report["counts"]["formal_ok"] += formal
+        try:
+            _check_workload_counts(row)
+        except (ValueError, TypeError) as error:
+            issue("workload_contract", error, row=index)
+        for field in NUMERIC_FIELDS:
+            if (report["environment_class"] == "wsl2" and native_only_metric(METRICS[field])
+                    and number(row.get(field)) is not None):
+                issue("unsupported_wsl_metric", f"WSL2 不允许记录 Native 专属指标 {field}", row=index, field=field)
+            raw = str(row.get(field, "nan")).strip().lower()
+            if raw not in MISSING and number(raw) is None:
+                issue("invalid_number", f"{field} 不是有限数值或 nan", row=index, field=field)
+            elif formal and raw in MISSING:
+                missing.setdefault(field, Counter())[missing_reason(field, row, metadata)] += 1
+        if formal:
+            for field, expected_value in _formula_checks(row).items():
+                actual_value = number(row.get(field))
+                # CSV 保存到 6 位小数，容忍加减的累计舍入，不把缺失分母解释为错误。
+                if actual_value is not None and not math.isclose(actual_value, expected_value, rel_tol=2e-5, abs_tol=2e-6):
+                    issue("formula_mismatch", f"{field}: 实际 {actual_value:g}，应为 {expected_value:g}", row=index, field=field)
+    report["missing_metrics"] = {name: dict(reasons) for name, reasons in missing.items()}
+    coverage = report["coverage"]
+    if coverage is not None:
+        formal = report["counts"]["rows"] - report["counts"]["warmup"]
+        report["measurement_status"] = (
+            "complete" if report["completion"] == "complete" and not coverage["missing"]
+            and not coverage["unexpected"] and formal > 0 and formal == report["counts"]["formal_ok"]
+            else "incomplete")
+    return report