tan-cli 0.7.0__py3-none-any.whl

tan/model/perf_apply.py

@@ -0,0 +1,721 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tier 2's MATCHING half: turn a customer's identity into the ONE
+`metadata/model_perf/` point that describes their machine, and turn that point
+into a `BackendReport`. `tan.model.perf` is deliberately only the READER (it
+finds points and refuses to rank them, by its own module docstring); this is
+the DECIDER, and `tan.model.check.check_model_backends` is its only caller.
+
+Split out of `tan.model.check` (tan-cli#791 review NIT (c)): this is pure
+string/decision logic with no subprocess in it -- `check.py` was 789 lines
+against the house `module_cap: 800`, and `MODULE_SIZE_BUDGET_LOG.md`'s own
+`ethos_u.py` entry already named exactly this shape of growth for a
+neighbouring module ("the extraction to make when this file next grows").
+This module takes the already-resolved Ethos-U target as a PARAMETER
+(`target`) rather than resolving it itself (`_headline_ethos_u_target` stays
+in `check.py`, which also needs it for `--exact`) -- passing it down avoids a
+`check.py` <-> `perf_apply.py` import cycle, and it costs nothing: the caller
+already has it in hand before either half of `check_model_backends`' per-model
+work runs.
+
+Everything below answers ONE question -- "did Alp Lab already measure THIS
+model, on THIS module, at THIS accelerator target?" -- and does nothing at all
+when the answer is no. That is not a courtesy, it is the contract: the same
+absence rule `npu-ops-v1` states for a missing op table applies here, so a
+customer whose model has never been benched (which is most of them) must get
+exactly the report they get today, note for note. `apply_perf_point`
+therefore returns @report ITSELF on every non-match path rather than a
+rebuilt copy, with no exception: "unchanged" is structural rather than a
+promise.
+
+A point's `target.core` is one of the fields that non-match rule protects
+(tan-cli#791 round-2 review item 1 / round-3's evidence-driven narrowing). The
+die a SoC spec describes may pair a given NPU to a specific core, or may not --
+alp-sdk's own schema says a shared SoC-level NPU legitimately declares no
+`paired_core` at all -- and `_resolve_perf_point` enforces exactly that
+DECLARED fact about the accelerator actually being screened, never a fact
+borrowed from a sibling NPU of the same backend that happens to declare one.
+See `_resolve_perf_point`'s own docstring for the sourced silicon evidence
+(the E8's Ethos-U85) that makes the distinction concrete.
+
+A BENCH POINT CANNOT CLAIM A COVERAGE VERDICT (tan-cli#1115). Reconciling
+`tan.model.perf.PerfPoint` against alp-sdk's REAL `model-perf-v1` schema
+removed `npu_ops`/`cpu_ops` -- fields the schema never actually carries (see
+that module's docstring, "DEAD FIELDS") -- so this module can no longer ask
+`coverage_from_placement` for a bench-derived `npu_coverage`. A matched point
+overlays only the figures alp-sdk's schema actually publishes today:
+`arena_bytes`, `req_sram_kib`, and latency once a capture campaign times one
+(merged per field, most-specific-wins, against whatever @report already had --
+`_merge_figure`, PR review blocker 3: a point that measured only latency must
+not blank a real `--exact` compile's own `arena_bytes`/`req_sram_kib`). This
+is a real, deliberate narrowing of what tier 2 claims versus an earlier,
+unreconciled version of this module (which asked a fictional
+`measured.npu_ops`/`cpu_ops` pair for a "fits"/"partial"/"cpu-only" verdict no
+alp-sdk document has ever actually carried): the schema's own description of
+`perf.latency_ms` says a capture campaign "can record fit/SRAM alone until a
+timing harness exists", and there is likewise no wire representation of an
+op-by-op NPU/CPU split for `apply_perf_point` to have been reading in the
+first place.
+
+COVERAGE ITSELF IS WITHHELD, NOT INHERITED, UNLESS @report ALREADY CARRIES A
+REAL PLACEMENT (PR review blocker 1 -- an earlier version of this PR
+inherited `npu_coverage`/`ops`/`uncosted_cpu_op_count`/`npu_placement_
+pct_real` from @report UNCONDITIONALLY, which silently promoted the static
+screen's name-level, capped-positive ESTIMATE -- `docs/model-check-static-
+screen.md`'s own vocabulary calls `partial`/`full-eligible` at
+`basis: "static-screen"` explicitly "Not a placement claim" -- into a
+`basis: "bench", confidence: "certain"` report, exactly the estimate-wearing-
+a-measurement's-clothes failure this module's `compute_on_npu_pct_max`
+handling already refuses two paragraphs down in `_perf_point_report`). The
+rule: those four fields carry forward from @report ONLY when `report.basis ==
+"compiled"` (a real, `--exact`-measured placement, safe to keep under
+`confidence: "certain"`); otherwise the rebased report states
+`npu_coverage: "undetermined"`, `ops: []`, `uncosted_cpu_op_count: 0`,
+`npu_placement_pct_real: None` -- the SRAM/arena/latency figures are still
+certain measurements, the coverage word honestly is not, and
+`docs/model-check-static-screen.md` documents this exact combination as
+legitimate. The one way `npu_coverage` still reaches `"fits"` at `basis:
+"bench"` is DECISION 1's agreement path below: the customer's own `--exact`
+compile already measured `"fits"` for real, the bench point corroborates it
+on arena/SRAM, and the rebased report inherits that real, `--exact`-measured
+verdict rather than a bench-authored one.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import replace
+from pathlib import Path
+
+from .analyze import COVERAGE_WITHHELD, BackendReport, OpVerdict
+from .perf import PerfPoint, coverage_from_placement, find_perf_points
+from .targets import TargetSpec
+
+
+def _placement_outcome(report: BackendReport, npu_ops: int | None,
+                        cpu_ops: int | None) -> tuple[str, list[OpVerdict], int] | None:
+    """(npu_coverage, ops, uncosted_cpu_op_count) for a MEASURED placement, or
+    `None` when there is no readable placement at all.
+
+    100% NPU is the only case that reports `"fits"`, and it drops `ops`: no
+    per-op verdict can add anything to "every operator ran on the NPU".
+    Partial or 0% KEEPS @report's static per-op verdicts AND its
+    uncosted-cpu-op count -- a real partial/0% result must erase neither
+    (MINOR review).
+
+    Takes the two COUNTS rather than a `Blob`: today's ONLY caller is
+    `tan.model.check._report_from_vela_compile`, off a real vela compile's own
+    "CPU/NPU operators = N" summary. It is NOT called for a bench perf point
+    any more (tan-cli#1115) -- alp-sdk's real schema carries no per-operator
+    placement counts on a published point, so there is nothing to feed this
+    with on that path; see this module's own docstring, "A BENCH POINT CANNOT
+    CLAIM A COVERAGE VERDICT". The coverage word itself comes from
+    `tan.model.perf.coverage_from_placement` -- the one function in tan
+    allowed to return `"fits"`."""
+    coverage = coverage_from_placement(npu_ops, cpu_ops)
+    if coverage is None:
+        return None
+    if coverage == "fits":
+        return coverage, [], 0
+    return coverage, report.ops, report.uncosted_cpu_op_count
+
+
+#: backend -> the leading token of the REAL `target.compiler_version` string
+#: that backend's compile adapter actually writes into a `.alpmodel` manifest
+#: (and, by the same vocabulary, into a bench point -- `model-perf-v1.schema.
+#: json`'s own description pins `compiler_version` to that manifest field).
+#: Measured directly against alp-sdk's producers, not the op-support-table
+#: filename vocabulary (`npu_ops/drpai/onnx-i8@translator-1.12.json`'s
+#: `translator` is a DIFFERENT namespace -- a table-authoring convention, not
+#: a compiler-identity string -- and an earlier version of this dict
+#: conflated the two, matching NEITHER of `drpai`/`deepx_dxm1`'s real points:
+#: tan-cli#1115 PR review, the issue's own failure mode one level down):
+#:
+#:   ethos_u     `_vela_version()`      "vela {version}" / "vela"
+#:               (ethos_u.py:21-24)
+#:   drpai       `_compiler_version()`  "drp-ai_tvm {version}" / "drp-ai_tvm"
+#:               (drpai.py:96-110)
+#:   deepx_dxm1  `_dxcom_version()`     "DX-COM {version}" / "dxcom" (bare,
+#:               (deepx.py:38-45)        differently-spelled fallback -- see
+#:                                        `tan.model.perf._toolchain_name`'s
+#:                                        own docstring for why that spelling
+#:                                        is not chased)
+#:
+#: Compared case-foldedly by `find_perf_points` (alp-sdk's three real
+#: producers do not agree on case -- `vela`/`drp-ai_tvm` lowercase, `DX-COM`
+#: upper -- and case is not part of a measurement's identity), so this dict's
+#: own values only need to be A correctly-spelled casing, not the specific
+#: one a given point happens to carry; `test_check.py`'s
+#: `test_perf_toolchain_matches_the_real_producer_strings` pins all three
+#: against these cited literal format strings.
+#:
+#: `cpu` is deliberately ABSENT rather than mapped to a made-up name: a
+#: backend with no entry here is simply never asked for a point, which is the
+#: right behaviour for one nobody benches. `cpu` STAYS absent on purpose
+#: (tan-cli#791 review, item 6): the schema's `target.backend` enum includes
+#: it, so alp-sdk COULD publish a CPU-baseline campaign, but
+#: `resolve_check_backends` (`tan.model.check`) already excludes `cpu` from
+#: what `tan model check` screens at all -- "how much of this model can
+#: target the NPU" has nothing to say about the fallback CPU path itself, and
+#: that decision predates tier 2. Wiring `cpu` in here without also
+#: revisiting that exclusion would publish points this reader can never be
+#: asked for, which is worse than not wiring it: a campaign planner who greps
+#: this dict for "which backends does tier 2 read" gets a true, complete
+#: answer as of THIS decision, made here rather than rediscovered from a
+#: silent no-op.
+_PERF_TOOLCHAIN = {"ethos_u": "vela", "drpai": "drp-ai_tvm", "deepx_dxm1": "DX-COM"}
+
+
+def _model_sha256(source: Path) -> str:
+    """Lowercase sha256 of @source's exact bytes -- the perf-point match key.
+
+    Chunked, because a real model is not a small file (a production ONNX runs
+    to tens of MB), and computed ONCE per `check` rather than once per backend.
+    Any `OSError` propagates exactly as `extract_ops`' own read of the same file
+    does: an unreadable source is `model.check-failed`, never a quietly degraded
+    report."""
+    digest = hashlib.sha256()
+    with source.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _resolve_hw_rev(sku: str, metadata_root: Path, declared: str | None) -> str | None:
+    """The module revision a perf point must have been measured on: the
+    customer's own `board.yaml` `som.hw_rev` when they declared one, else the
+    SKU preset's `default_hw_rev`.
+
+    That fallback is the SDK's own rule, not an invention -- `board.schema.json`
+    says of `som.hw_rev`: "Optional; the SDK falls back to the SKU preset's
+    `default_hw_rev` when omitted" -- and both spellings use the same `rN` keys
+    the perf-point schema requires, so no translation is involved.
+
+    `None` when neither answers, and `find_perf_points` matches NOTHING on a
+    `None`: an r2 measurement handed to a customer holding an r1 module is
+    exactly the "exactly measured, describes a different machine" failure that
+    put `hw_rev` in a point's identity in the first place (alp-sdk `f724d3e4`).
+    Soft-fail on a preset that does not exist or does not parse, matching
+    `resolve_ethos_u_variant`'s stance next door.
+
+    tan-cli#1116: NOT a pre-flight `preset_path.is_file()` -- that used to
+    gate the read below, and on Python <= 3.13 `Path.is_file()` RAISES for a
+    permission-denied ancestor -- `PermissionError`, `errno=13`, measured on
+    both 3.12.3 and 3.13.15 -- swallowing only `ENOENT`/`ENOTDIR`/`EBADF`/
+    `ELOOP` there. `pathlib`'s `_IGNORED_ERRNOS` CONSTANT that names those
+    four is itself gone a release earlier (3.13, `AttributeError` probing
+    for it), but the raising BEHAVIOUR it used to name outlives the constant
+    by one release and only actually changes in 3.14: there `is_file()`
+    swallows EVERY `OSError`, `EACCES` included, and returns `False`
+    instead (tan-cli#1116 review round 2 -- a pre-flight guard is dead on
+    3.14+ regardless of what it catches, and reasoning from either "the
+    constant still exists" or "I measured the raise" picks the wrong
+    boundary, since the two diverge for exactly the 3.13 release). NOT
+    `EACCES`, so a
+    preset whose CONTAINING directory the caller cannot traverse raised a raw
+    `PermissionError` right there, past this function's own "Soft-fail"
+    contract -- the exact `document_guards.read_catalog_document` trap ("not
+    a pre-flight `is_file()`"), just via `is_file()` instead of
+    `Path.exists()`. Reading straight through the `try` below answers the
+    same three cases (absent, a directory, no permission) through `OSError`
+    alone -- on EVERY supported interpreter, since it never calls `is_file()`
+    at all -- so the pre-flight added nothing a plain `FileNotFoundError`
+    from the read did not already give it. `UnicodeDecodeError` is also now
+    caught explicitly: it is a `ValueError`, not an `OSError` and not a
+    `yaml.YAMLError`, so a non-UTF-8 preset used to escape raw past this same
+    contract (measured, tan-cli#1116).
+
+    `declared` reaching here as `None` is itself a FAIL-CLOSED answer from the
+    caller, not a "customer said nothing" default: `tan.commands.model_cmd.
+    _declared_hw_rev` refuses the whole run outright (a `model.board-yaml-
+    invalid` issue) when `som.hw_rev` is present but not a usable string --
+    e.g. an unquoted YAML int (`hw_rev: 2`) -- rather than letting it fall
+    through to here and silently pick up the preset's `default_hw_rev`
+    instead (tan-cli#791 review MINOR 5: measured `{'som': {'hw_rev': 2}} ->
+    None` serving an r2 preset measurement to a customer who wrote r2 but
+    would have been served r1's if the preset defaulted there)."""
+    if declared:
+        return declared
+    preset_path = Path(metadata_root) / "e1m_modules" / f"{sku}.yaml"
+    import yaml  # noqa: PLC0415 -- deferred (tan-cli#810); see sdk_cmd's `_releases_opener`
+
+    try:
+        preset = yaml.safe_load(preset_path.read_text(encoding="utf-8")) or {}
+    except (OSError, UnicodeDecodeError, yaml.YAMLError):
+        return None
+    value = preset.get("default_hw_rev") if isinstance(preset, dict) else None
+    return str(value) if value else None
+
+
+def _part_declares_a_profile(target: TargetSpec) -> bool:
+    """Does the SoC spec that produced @target name a vela memory profile at
+    all -- ANY of `vela_memory_mode` / `vela_system_config` /
+    `vela_vendor_system_config`?
+
+    Mirrors `_profile_matches_the_part`'s own `stated` computation exactly,
+    because the two must agree: a part this says `True` about is one
+    `_resolve_perf_point` (below) now narrows on BEFORE the single-point
+    shortcut, and a part this says `False` about must not be narrowed on at
+    all -- narrowing unconditionally would turn "the part is silent" into
+    "reject every point", which is the opposite failure from the BLOCKER this
+    function exists to close (tan-cli#791 review item 1): a part that states
+    nothing has nothing for `_profile_matches_the_part` to ever agree with, so
+    an unconditional narrow would empty out even the correctly-profiled
+    ordinary case."""
+    system_config = target.vela_system_config or target.vela_vendor_system_config
+    return bool(target.vela_memory_mode) or bool(system_config)
+
+
+def _profile_matches_the_part(point: PerfPoint, target: TargetSpec) -> bool:
+    """Was @point captured under the memory profile THIS part declares?
+
+    The tiebreak, and the only one applied: the SoC spec's own
+    `npu_toolchain.vela` block (`TargetSpec.vela_memory_mode` /
+    `vela_system_config` / `vela_vendor_system_config`) is what `tan model
+    build` compiles this part under, so a point captured under the same profile
+    is the one describing THIS module. Comparing on a silicon fact rather than
+    on recency or on file order is the whole difference between choosing and
+    guessing -- the collision that put the profile into a point's identity left
+    a DRAM-backed capture as the arbitrary survivor on a part with no DRAM.
+
+    A field the SoC spec does not declare is not compared: `system_config` is
+    withheld from `TargetSpec` for every part shipped today (the Alif names live
+    only in a proprietary `.ini`), so on those parts this narrows on the memory
+    mode alone. `False` whenever there is nothing to compare at all -- an
+    unnarrowable ambiguity must fall through, not resolve to "everything
+    matches". CALLERS must gate this on `_part_declares_a_profile` first
+    (above) when using it to REJECT rather than to TIEBREAK: this function
+    alone cannot distinguish "nothing declared" from "declared and disagrees",
+    and only the caller knows which failure mode it is currently guarding."""
+    system_config = target.vela_system_config or target.vela_vendor_system_config
+    checks = [(target.vela_memory_mode, point.vela_memory_mode),
+              (system_config, point.vela_system_config)]
+    stated = [(declared, measured) for declared, measured in checks if declared]
+    return bool(stated) and all(declared == measured for declared, measured in stated)
+
+
+def _topology_core_ids(sku: str, metadata_root: Path) -> set[str]:
+    """Every core id @sku's OWN SoM preset `topology:` map declares -- the
+    physical cores this module actually has, keyed exactly as a perf point's
+    `target.core` must be (`metadata/schemas/model-perf-v1.schema.json`'s own
+    `target.core` description: "The SoM `topology:` role ... that issued this
+    measurement -- the core running the inference call, whether or not it
+    also owns the NPU doing the compute").
+
+    LEVEL 1 of the core check (tan-cli#791 round-2 review item 1). Applied
+    UNCONDITIONALLY, for every backend, regardless of whether the exact-match
+    query (`_resolve_perf_point`, below) already narrowed `core` to the
+    accelerator's own declared `paired_core`: a point naming a core the die
+    does not physically have is wrong either way. This is the check the
+    BLOCKER fix (the profile tiebreak, `_part_declares_a_profile`) left
+    undone, and it does not depend on any accelerator declaring a pairing at
+    all -- unlike the query's own narrowing, which only ever fires for an
+    accelerator that names one. Measured through `tan model check` (the
+    production path) on a part whose accelerator declares no `paired_core`: a
+    point claiming `core: "m55_hp"` -- a core that part does not have -- was
+    consumed at `basis: "bench", confidence: "certain"` with no check ever
+    having looked at `core` at all, because there was no `paired_core` for the
+    query to narrow on either.
+    This function is what makes that check possible for EVERY backend and
+    EVERY SKU, not only the ones that happen to pair an NPU to a core: a
+    die's `topology:` is required and always populated (all eleven shipped
+    presets declare one), so `p.core in _topology_core_ids(...)` is always a
+    real, checkable fact -- unlike `paired_core`, which is genuinely absent
+    for some accelerators by design.
+
+    `UnicodeDecodeError` is caught explicitly (tan-cli#1116, measured
+    escaping before this fix): it is a `ValueError`, not an `OSError` and
+    not a `yaml.YAMLError`, so a non-UTF-8 preset used to raise raw past
+    this function's own "refuses [to] `set()`" contract, same shape as
+    `_resolve_hw_rev`'s sibling fix next door.
+
+    By the time this runs, @sku's preset is already known to exist and parse
+    (`resolve_check_backends` -> `resolve_targets` succeeded before a single
+    backend was screened, reading the SAME file), so this re-reads it rather
+    than threading a parsed doc all the way down here, matching
+    `_resolve_hw_rev`'s own stance next door. `set()` -- which REFUSES every
+    point, never admits one -- only for a preset that dropped `topology:`
+    entirely or left it malformed, which no shipped SoM does: a core this
+    function cannot vouch for is not proof the SKU has it, the same "absent
+    means refuse" reading `find_perf_points` already gives a `None` `hw_rev`
+    (`PerfPoint.hw_rev` is REQUIRED and non-empty, so it can never equal an
+    unresolvable query value either)."""
+    preset_path = Path(metadata_root) / "e1m_modules" / f"{sku}.yaml"
+    import yaml  # noqa: PLC0415 -- deferred (tan-cli#810); see sdk_cmd's `_releases_opener`
+
+    try:
+        preset = yaml.safe_load(preset_path.read_text(encoding="utf-8")) or {}
+    except (OSError, UnicodeDecodeError, yaml.YAMLError):
+        return set()
+    topology = preset.get("topology") if isinstance(preset, dict) else None
+    return set(topology) if isinstance(topology, dict) else set()
+
+
+def _one_line(text: str) -> str:
+    """@text with every run of whitespace collapsed to a single space.
+
+    Applied to every FOREIGN string a perf-point note quotes (the capture
+    citation, the toolchain version, the hardware revision): a note is one line
+    in both the text report and the JSON envelope by contract, and these come
+    out of a document in ANOTHER repository that this reader deliberately does
+    not schema-validate."""
+    return " ".join(text.split())
+
+
+def _perf_measured_clauses(point: PerfPoint) -> list[str]:
+    """The `perf` figures @point actually carries, as note clauses.
+
+    A figure the point omits produces NO clause -- it was not measured, and
+    the note must not imply a zero. `latency_runs` travels with the latency
+    for the same reason the schema requires it: a latency without a run count
+    is a single shot wearing a measurement's clothes. NO operator-placement
+    clause: alp-sdk's real schema carries no per-op NPU/CPU split (tan-cli
+    #1115) -- see this module's own docstring, "A BENCH POINT CANNOT CLAIM A
+    COVERAGE VERDICT" -- so there is nothing sourced to phrase one from."""
+    clauses = []
+    if point.arena_bytes is not None:
+        clauses.append(f"arena {point.arena_bytes} bytes")
+    if point.req_sram_kib is not None:
+        clauses.append(f"{point.req_sram_kib} KiB resident SRAM")
+    if point.latency_ms_mean is not None and point.latency_runs is not None:
+        latency = f"{point.latency_ms_mean} ms mean"
+        if point.latency_ms_p95 is not None:
+            latency += f", {point.latency_ms_p95} ms p95"
+        clauses.append(f"{latency} over {point.latency_runs} runs")
+    return clauses
+
+
+def _perf_identity(point: PerfPoint) -> str:
+    """The measurement identity, as one readable clause -- module, hardware
+    revision, driving core, accelerator target, the exact compiler build, and
+    the memory profile the figures describe. Every one of them is in the note
+    because every one of them CHANGES THE NUMBER (alp-sdk `f724d3e4`), and a
+    customer sizing hardware has to be able to see which machine was measured.
+
+    The CORE is the one the match rule may leave unnarrowed -- where the
+    SPECIFIC accelerator being screened declares no `paired_core` of its own
+    (every drpai/deepx_dxm1 SoM; and the
+    E8's Ethos-U85, genuinely shared silicon rather than core-private -- see
+    `_resolve_perf_point`) -- so stating it here is the only way the customer
+    learns which one this point actually describes. `compiler_version` is
+    always stated verbatim (e.g. `"vela 4.1.0"`): the tier-2 customer has no
+    local toolchain to compare it against, so the exact build this point was
+    captured under is the only fact they get. The PROFILE is there for the
+    reason the schema makes it required on an Ethos-U point at all: an arena
+    captured under a DRAM-backed profile is exactly measured and describes the
+    wrong machine, and hiding it would re-open on the reading side the
+    ambiguity the schema closed on the writing side.
+
+    THE PROFILE CLAUSE IS `ethos_u`-ONLY (tan-cli#791 round-2 review item 5).
+    `vela_system_config`/`vela_memory_mode` are only ever narrowed or
+    verified against silicon for `ethos_u` -- `_part_declares_a_profile`/
+    `_profile_matches_the_part` run only when `target is not None`, and
+    `target` is `None` for every OTHER backend by construction
+    (`tan.model.check.check_model_backends` only resolves one for
+    `backend == "ethos_u"`). Nothing sourced exists to check a drpai/
+    deepx_dxm1 point's profile fields against, which is a DEFENSIBLE gap --
+    there is no vela-shaped profile concept on those toolchains to check --
+    but printing whatever those two fields happen to hold as if it were this
+    point's verified memory profile is not: measured, a drpai point carrying
+    a stray Ethos-U85 `Ethos_U85_SYS_DRAM_Mid`/`Dedicated_Sram_384KB` pair
+    printed that nonsense verbatim into the customer-facing note. So this
+    clause is withheld outright for every backend but `ethos_u`, regardless
+    of what the point's own fields carry."""
+    target = point.accel_config or point.backend
+    profile = ("" if point.backend != "ethos_u" else
+               ", ".join(_one_line(p) for p in
+                        (point.vela_system_config, point.vela_memory_mode) if p))
+    return (f"{point.sku} {_one_line(point.hw_rev)} (core {_one_line(point.core)}) "
+            f"at {_one_line(target)} with {_one_line(point.compiler_version)}"
+            + (f" ({profile})" if profile else ""))
+
+
+def _perf_point_note(point: PerfPoint, *, corroborated: bool) -> str:
+    """The one-line note a `basis: "bench"` report leads with.
+
+    Carries `capture.bench_id` verbatim (whitespace-collapsed) -- WHICH
+    physical bench/rig captured this point (e.g. `"e1m-aen-evk-01"`), not a
+    capture artefact's own citation (that mislabel, "raw capture", used to be
+    the note's own wording -- tan-cli#1115 PR review minor) -- because a
+    number nobody can trace back to a specific rig is not reproducible, and a
+    perf point is worth exactly what its reproducibility is. Closes by saying
+    that a local compile can differ -- true for every backend, unlike an
+    `--exact` suggestion, which would be wrong advice on the two
+    license-gated ones."""
+    tail = ("This host's own compile agrees with it." if corroborated else
+            "A compile on your own host can differ if its toolchain profile "
+            "differs from the one recorded here.")
+    return (f"bench: Alp Lab measured this exact model on {_perf_identity(point)} "
+            f"-- {'; '.join(_perf_measured_clauses(point))}. Captured "
+            f"{_one_line(point.capture_date)} on bench "
+            f"{_one_line(point.capture_bench_id)}. {tail}")
+
+
+def _perf_disagreements(point: PerfPoint, report: BackendReport) -> list[str]:
+    """Every concrete way @point and the customer's OWN `basis: "compiled"`
+    @report differ -- empty when they agree on everything both measured.
+
+    "Disagrees" is defined on the two figures BOTH sides really produce: the
+    tensor arena and the resident SRAM. NOT the placement verdict any more
+    (tan-cli#1115): alp-sdk's real schema carries no bench-measured
+    operator-placement split for a bench point to disagree about (see this
+    module's own docstring, "A BENCH POINT CANNOT CLAIM A COVERAGE VERDICT")
+    -- `report.npu_coverage` is a real `--exact` compile's OWN verdict either
+    way, so there is nothing left to compare it against. Latency has no
+    compiled counterpart to disagree with either, and a figure EITHER side
+    did not report is never a disagreement: absence is not evidence here any
+    more than anywhere else in this tier."""
+    diffs: list[str] = []
+    for label, unit, measured, compiled in (
+            ("arena", "bytes", point.arena_bytes, report.arena_bytes),
+            ("SRAM", "KiB", point.req_sram_kib, report.req_sram_kib)):
+        if measured is not None and compiled is not None and measured != compiled:
+            diffs.append(f"{label} (bench {measured} {unit}, local compile {compiled} {unit})")
+    return diffs
+
+
+def _perf_disagreement_note(point: PerfPoint, diffs: list[str]) -> str:
+    """Why the customer's own compile is being reported and OUR measurement is
+    not -- with the measurement still named, so nothing is hidden."""
+    return (f"--exact wins here: Alp Lab's bench point for this exact model on "
+            f"{_perf_identity(point)} ({_one_line(point.capture_bench_id)}) "
+            f"disagrees with this host's own compile -- {'; '.join(diffs)}. The "
+            f"LOCAL compile is what is reported above: it ran this host's own "
+            f"toolchain and profile, which is what a build here would produce.")
+
+
+#: A note whose text starts with `"--exact"` is a diagnostic about THIS RUN's
+#: HOST/toolchain environment for the customer's `--exact` request (vela
+#: absent, license-gated, footprint refused, ...) -- every HOST-fact
+#: note-authoring site in `tan.model.check`'s exact-compile path shares this
+#: prefix by construction (`_license_gated_exact_note`, `_footprint_refused_
+#: note`, and every degrade branch in `_exact_ethos_u`/`_vela_placement_
+#: unreadable`). The BASIS-clause sites in that SAME path deliberately do
+#: NOT share it -- "This stays the static screen."/"Reporting the static
+#: screen instead." (`check.py:233`, `:341`, `:387`, `:429`, `:518`) -- and
+#: that is by design, not an oversight: `_perf_point_report` (below) uses the
+#: prefix to tell the two kinds of note apart. The former survives a re-base
+#: onto a bench point because it is still true of this run; the latter does
+#: not, because it describes a basis the report no longer has (tan-cli#791
+#: review item 4: measured the "--exact was requested, but vela is not on
+#: PATH" note present with no perf point and GONE the moment one matched).
+_EXACT_HOST_NOTE_PREFIX = "--exact"
+
+
+def _merge_figure(point_value, report_value):
+    """THE MERGE RULE for every footprint/latency figure a rebase touches
+    (tan-cli#1115 PR review blocker 3): @point's own value when it has one,
+    else whatever @report already carried -- MOST-SPECIFIC-WINS, per field,
+    never a blanket "the point's block replaces the report's".
+
+    A matched bench point is not guaranteed to carry every figure (the
+    schema's `perf.latency_ms` is optional even where `req_sram_kib`/
+    `arena_bytes` are schema-required, and this reader stays defensive
+    against a malformed point missing even those -- see `tan.model.perf`'s
+    own `test_a_missing_or_malformed_perf_block_still_reads_the_identity`),
+    so a rebase that unconditionally overwrote every figure with @point's
+    (`None` included) blanked a REAL `--exact` compile's own measured
+    `arenaBytes`/`reqSramKib` the moment a matched point recorded only
+    latency -- reproduced: a compiled report's `arena_bytes=123456,
+    req_sram_kib=121` became `None, None` under `basis: "bench", confidence:
+    "certain"`, directly contradicting `apply_perf_point`'s own promise that
+    an under-informative point "cannot degrade a report by even a note".
+    Applied uniformly to every figure below, not only the two that were
+    reproduced: a bench point's latency is likewise never allowed to blank a
+    real compile's (today impossible in practice -- `_report_from_vela_
+    compile` never sets latency -- but the rule is stated once, for every
+    field, rather than fixed only at the two sites a repro happened to hit."""
+    return point_value if point_value is not None else report_value
+
+
+def _perf_point_report(report: BackendReport, point: PerfPoint) -> BackendReport:
+    """@report re-based on @point: `basis: "bench"`, `confidence: "certain"`.
+
+    Drops @report's BASIS-describing notes and leads with the bench note,
+    exactly as `tan.model.check._report_from_vela_compile` does for a real
+    compile -- those notes describe a basis this report no longer has. Notes
+    that instead describe the HOST/toolchain environment for a `--exact`
+    request (`_EXACT_HOST_NOTE_PREFIX`) are still true of this run and are
+    KEPT, appended after the bench note (tan-cli#791 review item 4).
+
+    Two rules, both spelled out in full in this module's own docstring
+    ("A BENCH POINT CANNOT CLAIM A COVERAGE VERDICT" -- read that first):
+    footprint/latency figures merge PER FIELD, most-specific-wins
+    (`_merge_figure`, PR review blocker 3); coverage/placement fields carry
+    from @report ONLY when `report.basis == "compiled"`, else `npu_coverage`
+    is withheld to `"undetermined"` (PR review blocker 1). `compute_on_npu_
+    pct_max` is FORCED to `None` regardless -- `analyze.BackendReport`'s own
+    field comment: that MAC-weighted figure is "ONLY at basis: static-screen",
+    same reason it is already `None` at `basis: "compiled"`.
+
+    `sram_fit` (tan-cli#1288) rides the SAME `real_placement` gate as
+    `ops`/`npu_placement_pct_real`: it is a verdict about the COMPILED blob a
+    real `--exact` run just produced, not something a bare bench point can
+    independently corroborate (alp-sdk's `model_perf/` schema carries no
+    SRAM0-residency figure of its own, tan-cli#1115's "DEAD FIELDS"), so it
+    only survives the rebase when this report was ALREADY `basis: "compiled"`
+    -- otherwise it is dropped to `None`, exactly like `ops`'s own
+    withhold-when-not-corroborated shape."""
+    host_notes = [n for n in report.notes if n.startswith(_EXACT_HOST_NOTE_PREFIX)]
+    real_placement = report.basis == "compiled"
+    return BackendReport(
+        backend=report.backend, variant=report.variant, table=report.table,
+        npu_coverage=report.npu_coverage if real_placement else COVERAGE_WITHHELD,
+        compute_on_npu_pct_max=None,
+        npu_placement_pct_real=report.npu_placement_pct_real if real_placement else None,
+        uncosted_cpu_op_count=report.uncosted_cpu_op_count if real_placement else 0,
+        ops=report.ops if real_placement else [],
+        basis="bench", confidence="certain",
+        arena_bytes=_merge_figure(point.arena_bytes, report.arena_bytes),
+        req_sram_kib=_merge_figure(point.req_sram_kib, report.req_sram_kib),
+        latency_ms_mean=_merge_figure(point.latency_ms_mean, report.latency_ms_mean),
+        latency_ms_p95=_merge_figure(point.latency_ms_p95, report.latency_ms_p95),
+        latency_runs=_merge_figure(point.latency_runs, report.latency_runs),
+        perf_ref=point.capture_bench_id,
+        notes=[_perf_point_note(point, corroborated=report.basis == "compiled"), *host_notes],
+        sram_fit=report.sram_fit if real_placement else None,
+    )
+
+
+def _resolve_perf_point(*, backend: str, sku: str, model_sha256: str,
+                         hw_rev: str | None, metadata_root: Path,
+                         target: TargetSpec | None) -> PerfPoint | None:
+    """The ONE point that describes this customer's module, or `None`.
+
+    @target is the ALREADY-RESOLVED Ethos-U accelerator
+    (`tan.model.check._headline_ethos_u_target`'s answer for @backend ==
+    `"ethos_u"`, `None` for every other backend) -- passed in rather than
+    resolved here so this module never has to import `check.py` back.
+
+    Narrows on everything tan can SOURCE: the SKU, the module revision, the
+    accel config `--exact` would compile for, the model's own bytes, and the
+    toolchain name this backend's points are keyed by. It does NOT narrow on
+    the toolchain VERSION -- there is no local toolchain to read one off in the
+    tier-2 premise, and a point measured at another version is still OUR
+    measurement (decision 1).
+
+    CORE narrows in TWO WAYS, and both are DECLARED facts -- never an
+    inference borrowed from elsewhere on the die (tan-cli#791 round-3,
+    driven by newly-sourced silicon evidence; see below). The exact-match
+    query below narrows to @target's OWN `paired_core` when @target declares
+    one -- the case for every Ethos-U55 published today, including both of
+    the E8's (`m55_hp`/`m55_he`): that pairing is a fact about the SAME
+    accelerator being screened, so enforcing it is sound. LEVEL 1
+    (`_topology_core_ids`), applied UNCONDITIONALLY for every backend
+    regardless of what @target declares: a point's core must exist in @sku's
+    OWN `topology:` map at all, full stop -- this is what catches a point
+    claiming `core: "m55_hp"` on a SoM whose topology has no such core
+    or any other core nothing on the module
+    has ever had.
+
+    WHERE @target DECLARES NO `paired_core` OF ITS OWN, core narrowing STOPS
+    at level 1 -- tan infers NOTHING further, and in particular never borrows
+    a SIBLING NPU's pairing on the same die. A prior round of this reader did
+    exactly that: it took the UNION of `paired_core` across every NPU of
+    @backend on the die and applied it even to an accelerator that named no
+    pairing of its own, on the reasoning that the E8's Ethos-U85 (unpaired)
+    shares a die with two Ethos-U55s (paired to `m55_hp`/`m55_he`), so a point
+    naming `a32_cluster` for the U85 "must" be wrong. Newly-sourced silicon
+    evidence proves that inference wrong: the U85's `NPU_HG_BASE` register
+    alias is byte-identical across BOTH M55 cores' generated headers, its
+    vendor DFP `<feature>` element carries no `Pname` at all (unlike the two
+    Ethos-U55s' `Pname="M55_HP"`/`"M55_HE"`), and it is clock-gated
+    SYSTEM-side (`SHMEM_CLK_CTRL.ZAPHOD_CKOR`) rather than from either core's
+    own config block -- it is genuinely shared SoC-level silicon, not a
+    core-private accelerator that merely forgot to declare its pairing. alp-
+    sdk's own `soc-spec-v1.schema.json` says exactly that is legitimate:
+    `paired_core`'s own field description says to "Omit for a shared /
+    non-core-paired NPU". A point naming ANY core @sku's own topology admits
+    (level 1) is therefore accepted for such an accelerator, `a32_cluster`
+    included -- accepting it is not a claim that the U85 CAN be driven from
+    the A32 cluster, only that the customer's own report of what they ran is
+    not contradicted by any sourced fact. Nothing sourced says it cannot, either:
+    there is no A32 SVD view and no A32 board devicetree NPU node to check
+    either way, so refusing the core would have been an equally unsourced
+    assertion in the OTHER direction. Only where @target declares no pairing
+    at all -- e.g. every drpai/deepx_dxm1 SoM today -- does level 1 alone
+    decide, exactly as it always did.
+
+    THE PROFILE TIEBREAK NARROWS BEFORE THE SINGLE-POINT SHORTCUT, not after
+    (tan-cli#791 review item 1, the BLOCKER). A part that declares a vela
+    memory profile (`_part_declares_a_profile`) only ever matches a point
+    captured under that SAME profile -- a lone point captured under a profile
+    the part does NOT declare (a DRAM-backed default measured against a
+    Sram_Only part) must be refused exactly as decisively as a second,
+    wrongly-profiled point in a multi-point tie already was: the old code
+    applied this ONLY once two or more points survived the sourced filters
+    above, so a single wrong-profile point was returned unfiltered at
+    `basis: "bench", confidence: "certain"` -- overstating resident SRAM by
+    5.3x in the measured case (a DRAM-backed default capture against
+    E8-class e8.json's `Sram_Only`-declaring part). Applied only where the
+    part actually states a profile: narrowing on a part that states nothing
+    would reject every point outright, the opposite failure.
+
+    THE MULTI-MATCH RULE, for what is left. More than one point can
+    legitimately still stand -- one model, one module, one core, one
+    toolchain, captured under two different vela profiles the PART itself
+    leaves unconstrained (`_part_declares_a_profile` false for it). Nothing
+    further is picked: still several, or none once narrowed, falls through to
+    the next fidelity tier, silently, rather than guessing."""
+    toolchain = _PERF_TOOLCHAIN.get(backend)
+    if toolchain is None:
+        return None
+    if backend == "ethos_u" and target is None:
+        return None
+    points = find_perf_points(
+        sku=sku, backend=backend, accel_config=target.accel_config if target else "",
+        model_sha256=model_sha256, toolchain=toolchain, hw_rev=hw_rev,
+        core=target.paired_core if target else None, metadata_root=metadata_root)
+    topology_cores = _topology_core_ids(sku, metadata_root)
+    points = [p for p in points if p.core in topology_cores]
+    if target is not None and _part_declares_a_profile(target):
+        points = [p for p in points if _profile_matches_the_part(p, target)]
+    return points[0] if len(points) == 1 else None
+
+
+def apply_perf_point(report: BackendReport, *, backend: str, sku: str,
+                      model_sha256: str, hw_rev: str | None,
+                      metadata_root: Path, target: TargetSpec | None) -> BackendReport:
+    """Tier 2, or @report untouched.
+
+    Every early return hands back the SAME object, with no exception: an
+    absent, ambiguous, fixture-marked, or empty point cannot degrade a report
+    by even a note. The last of those is the subtle one: a point that carries
+    none of `arena_bytes`/`req_sram_kib`/`latency_ms_mean` -- schema-legal but
+    with nothing left for this function to actually contribute -- must not
+    re-base the report to `basis: "bench"` over an empty note; that would
+    claim a measurement said something it didn't.
+
+    A MATCHED POINT NEVER DETERMINES `npu_coverage` ITSELF -- see this
+    module's own docstring ("A BENCH POINT CANNOT CLAIM A COVERAGE VERDICT")
+    and `_perf_point_report`'s for the full withhold-unless-`"compiled"` rule.
+
+    DECISION 1 (tier-2 plan, Task 4): a `basis: "compiled"` report -- the
+    customer really does hold the toolchain and really did compile -- WINS
+    over a disagreeing point, named in a note instead; their profile may not
+    be ours, and the number they can act on is the one their machine
+    produced. THE POINT'S OWN LATENCY AND CAPTURE CITATION STILL RIDE AS
+    FIELDS on that disagreement report (tan-cli#791 review item 3): a compile
+    has no wall-clock or raw-capture counterpart to disagree WITH, so they
+    are never part of `_perf_disagreements`' comparison, only offered
+    alongside the winning LOCAL numbers -- without this `perfRef` was `null`
+    in the same envelope whose own note prose quoted it.
+
+    When the two AGREE the point wins, because it adds measured wall-clock
+    latency and a traceable capture no compile can produce, and the local
+    compile corroborating it is said out loud."""
+    point = _resolve_perf_point(backend=backend, sku=sku, model_sha256=model_sha256,
+                                 hw_rev=hw_rev, metadata_root=metadata_root, target=target)
+    if point is None:
+        return report
+    if (point.arena_bytes is None and point.req_sram_kib is None
+            and point.latency_ms_mean is None):
+        return report
+    if report.basis == "compiled":
+        diffs = _perf_disagreements(point, report)
+        if diffs:
+            return replace(
+                report, notes=[*report.notes, _perf_disagreement_note(point, diffs)],
+                perf_ref=point.capture_bench_id,
+                latency_ms_mean=point.latency_ms_mean,
+                latency_ms_p95=point.latency_ms_p95,
+                latency_runs=point.latency_runs)
+    return _perf_point_report(report, point)