nthlayer-common 2.1.2__tar.gz → 3.0.0__tar.gz

{nthlayer_common-2.1.2 → nthlayer_common-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nthlayer-common
-Version: 2.1.2
+Version: 3.0.0
 Summary: Shared utilities for the NthLayer ecosystem
 License: Apache-2.0
 Requires-Python: >=3.11

{nthlayer_common-2.1.2 → nthlayer_common-3.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nthlayer-common"
-version = "2.1.2"
+version = "3.0.0"
 description = "Shared utilities for the NthLayer ecosystem"
 readme = "README.md"
 requires-python = ">=3.11"

{nthlayer_common-2.1.2 → nthlayer_common-3.0.0}/src/nthlayer_common/manifest/__init__.py

@@ -75,8 +75,12 @@ from nthlayer_common.manifest.parser.v1 import OpenSRMParseError
 from nthlayer_common.manifest.parser.v2 import OpenSRMV2ParseError
 from nthlayer_common.manifest.scan import (
     MANIFEST_SUFFIXES,
+    ManifestCollisionWarning,
+    ManifestScan,
+    SuffixCollision,
     foreign_yaml_reason,
     iter_manifest_files,
+    scan_manifest_files,
 )
 
 __all__ = [
@@ -102,8 +106,12 @@ __all__ = [
     "valid_service_types_phrase",
     # Directory scanning
     "MANIFEST_SUFFIXES",
+    "ManifestCollisionWarning",
+    "ManifestScan",
+    "SuffixCollision",
     "foreign_yaml_reason",
     "iter_manifest_files",
+    "scan_manifest_files",
     # Enums
     "DependencyCriticality",
     "SourceFormat",

{nthlayer_common-2.1.2 → nthlayer_common-3.0.0}/src/nthlayer_common/manifest/openslo/parser.py

@@ -16,6 +16,10 @@ from typing import Any
 import yaml
 
 from nthlayer_common.manifest.models import SLODefinition
+from nthlayer_common.manifest.target_validation import (
+    check_finite,
+    require_number,
+)
 
 
 class OpenSLOParseError(Exception):
@@ -114,9 +118,7 @@ def _parse_openslo_document(data: dict[str, Any]) -> SLODefinition:
         raise OpenSLOParseError(f"OpenSLO '{name}' has no objectives")
 
     objective = objectives[0]
-    target = objective.get("target")
-    if target is None:
-        raise OpenSLOParseError(f"OpenSLO '{name}' objective missing target")
+    target = _objective_target_percent(objective, name)
 
     # Parse indicator
     indicator = spec.get("indicator", {})
@@ -182,8 +184,11 @@ def _parse_openslo_document(data: dict[str, Any]) -> SLODefinition:
     description = objective.get("displayName") or metadata.get("displayName")
 
     return SLODefinition(
+        # No float(): _objective_target_percent already returns one, having gone
+        # through require_number. The redundant cast was a leftover from when
+        # this read objective["target"] directly [opensrm-ocvu].
         name=name,
-        target=float(target),
+        target=target,
         slo_type=slo_type,
         window=window,
         unit=unit,
@@ -195,6 +200,74 @@ def _parse_openslo_document(data: dict[str, Any]) -> SLODefinition:
     )
 
 
+def _objective_target_percent(objective: dict[str, Any], name: str) -> float:
+    """An OpenSLO objective's target, as the canonical 0-100 percentage.
+
+    OpenSLO accepts EITHER ``target`` (a fraction in [0,1)) OR ``targetPercent``
+    (0-100), exactly one of them. NthLayer's internal convention is 0-100 for
+    every consumer (nthlayer-common CLAUDE.md hard rule 1), so a fraction is
+    converted here — at the inbound boundary — and a percentage is taken as-is.
+
+    This boundary was missing entirely [opensrm-ocvu]. The outbound one has
+    always existed (nthlayer_generate/slos/pipeline.py divides by 100), so a
+    ratio reached SLODefinition.target unconverted and every consumer comparing
+    a target to a measured value got an answer 100x out, silently, depending
+    only on which format the manifest happened to be written in.
+
+    It also broke the documented v1 -> v2 migration: v1_compat converts a v1
+    percentage to a ratio for the OpenSLO document it emits, and reading that
+    back without converting turned a 99.9 target into 0.999. The module
+    promised the output "round-trips through parse_opensrm_v2"; it did not.
+    """
+    has_target = "target" in objective and objective["target"] is not None
+    has_percent = (
+        "targetPercent" in objective and objective["targetPercent"] is not None
+    )
+
+    if has_target and has_percent:
+        # OpenSLO requires exactly one. Picking a winner here would let two
+        # disagreeing values sit in a manifest with only one taking effect.
+        raise OpenSLOParseError(
+            f"OpenSLO '{name}' objective sets both target and targetPercent; "
+            f"OpenSLO permits exactly one"
+        )
+    # Both branches go through require_number + check_finite, the same guards
+    # the JUDGMENT boundary uses, re-raised as this parser's own error type
+    # [opensrm-ocvu]. Without them this function — which this bead added — had
+    # the two defects the judgment side had already been fixed for:
+    #
+    #   target: .nan  -> SLODefinition.target = nan, and with a contract
+    #                    promise validate_contracts() returned [], a breach
+    #                    reporting CLEAN. Identical outcome, identical field.
+    #   target: {}    -> bare TypeError out of float(), which is not a type
+    #                    this parser declares.
+    #
+    # RANGE is deliberately NOT checked here. `targetPercent: 50` meaning "50%"
+    # versus `target: 50` meaning a 5000% floor is a real ambiguity, but
+    # rejecting it would also reject `target` values this parser accepts today,
+    # and plain `target` has been unranged since long before this bead. That is
+    # a scoped decision, not a fix to make inside one.
+    try:
+        if has_percent:
+            value = require_number(
+                "targetPercent", objective["targetPercent"],
+                what="objective target",
+            )
+            check_finite("targetPercent", value, what="objective target")
+            return value
+        if has_target:
+            value = require_number(
+                "target", objective["target"], what="objective target",
+            )
+            check_finite("target", value, what="objective target")
+            return value * 100.0
+    except ValueError as exc:
+        raise OpenSLOParseError(f"OpenSLO '{name}': {exc}") from exc
+    raise OpenSLOParseError(
+        f"OpenSLO '{name}' objective missing target (or targetPercent)"
+    )
+
+
 def _extract_query(metric_source: dict[str, Any]) -> str | None:
     """Extract PromQL query from an OpenSLO metricSource."""
     ms_type = metric_source.get("type", "")

{nthlayer_common-2.1.2 → nthlayer_common-3.0.0}/src/nthlayer_common/manifest/parser/v1.py

@@ -42,6 +42,10 @@ from nthlayer_common.manifest.models import (
     TelemetryEvent,
 )
 from nthlayer_common.manifest.parser._shared import parse_observability
+from nthlayer_common.manifest.target_validation import (
+    check_finite,
+    require_number,
+)
 from nthlayer_common.manifest.v1_compat import (
     convert_v1_contract,
     default_measurement,
@@ -287,9 +291,27 @@ def _parse_slos(
             measurement = default_measurement(judgment_type, window)
             statistical_requirements = default_statistical_requirements(judgment_type)
 
+        # Guarded the same way as the v2 classical path [opensrm-ocvu]. v1 was
+        # the LAST unguarded writer of SLODefinition.target, and leaving it so
+        # would have recreated this bead's own subject one level down: v2
+        # classical rejecting a NaN target while v1 classical accepted it.
+        # Measured before the guard — `slos: {availability: {target: .nan}}`
+        # with a contract gave target=nan and validate_contracts() -> [], a
+        # breach reporting CLEAN; `target: {}` gave a bare TypeError.
+        #
+        # RANGE is not checked, matching the v2 classical path exactly: plain
+        # targets have been unranged in both formats since long before this
+        # bead, and rejecting out-of-range would reject manifests that parse
+        # today. That remains a scoped decision.
+        try:
+            numeric_target = require_number(name, target, what="SLO target")
+            check_finite(name, numeric_target, what="SLO target")
+        except ValueError as exc:
+            raise OpenSRMParseError(f"SLO '{name}': {exc}") from exc
+
         slo = SLODefinition(
             name=name,
-            target=float(target),
+            target=numeric_target,
             slo_type=slo_type,
             window=config.get("window", "30d"),
             unit=config.get("unit"),

{nthlayer_common-2.1.2 → nthlayer_common-3.0.0}/src/nthlayer_common/manifest/parser/v2.py

@@ -28,7 +28,6 @@ from nthlayer_common.manifest.models import (
     FallbackDeclaration,
     Instrumentation,
     JudgmentMeasurement,
-    JudgmentPromise,
     Outcomes,
     Ownership,
     ProbeConfig,
@@ -53,6 +52,11 @@ from nthlayer_common.manifest.openslo.parser import (
     parse_openslo_slos,
 )
 from nthlayer_common.manifest.parser._shared import parse_observability
+from nthlayer_common.manifest.target_validation import (
+    JUDGMENT_TARGET_FIELDS,
+    judgment_promise,
+    judgment_target_percent,
+)
 
 logger = structlog.get_logger()
 
@@ -410,19 +414,7 @@ def _extract_judgment_target(
 
     Each judgment type has a different target field name in the spec.
     """
-    # Type-specific target field names
-    target_fields: dict[str, str] = {
-        "reversal_rate": "maximum_reversal_rate",
-        "high_confidence_failure": "maximum_failure_rate",
-        "audit_sampling": "audit_completion_rate",
-        "outcomes": "desired_outcome_rate",
-        "escalation": "maximum_escalation_rate",
-        "segments": "maximum_variance_from_overall",
-        "stability": "maximum_drift",
-        "calibration": "maximum_brier_score",
-    }
-
-    field_name = target_fields.get(judgment_type)
+    field_name = JUDGMENT_TARGET_FIELDS.get(judgment_type)
     if not field_name:
         raise OpenSRMV2ParseError(
             f"No target field mapping for judgment_type '{judgment_type}'"
@@ -434,7 +426,15 @@ def _extract_judgment_target(
             f"Judgment SLO '{name}' missing target.{field_name}"
         )
 
-    return float(value)
+    # No float() here — judgment_target_percent validates the type itself and
+    # raises ValueError, whereas float() raised TypeError for None / dict /
+    # list, a type this parser does not declare. Re-raised as this parser's own
+    # error so a malformed target is indistinguishable in KIND from a missing
+    # one, which is raised above [opensrm-ocvu].
+    try:
+        return judgment_target_percent(field_name, value)
+    except ValueError as exc:
+        raise OpenSRMV2ParseError(f"Judgment SLO '{name}': {exc}") from exc
 
 
 def _parse_judgment_measurement(
@@ -556,11 +556,16 @@ def _parse_contracts(contracts_data: list[dict[str, Any]]) -> list[ReliabilityCo
         promise_data = c_data.get("promise", {})
         judgment_promises = []
         for jtype, threshold in promise_data.get("judgment", {}).items():
-            judgment_promises.append(JudgmentPromise(
-                judgment_type=jtype,
-                threshold=float(threshold),
-                direction="below",  # contract thresholds are maximums (lower is better)
-            ))
+            # Threshold and direction decided together, in one place shared with
+            # the v1 path — see judgment_promise() [opensrm-ocvu]. Re-raised as
+            # this parser's own error type; a `judgment: {reversal_rate:}` typo
+            # otherwise escaped as a bare TypeError.
+            try:
+                judgment_promises.append(judgment_promise(jtype, threshold))
+            except ValueError as exc:
+                raise OpenSRMV2ParseError(
+                    f"Contract '{name}' promise: {exc}"
+                ) from exc
 
         promise = ContractPromise(
             availability=promise_data.get("availability"),

nthlayer_common-3.0.0/src/nthlayer_common/manifest/scan.py

@@ -0,0 +1,375 @@
+"""Scanning a directory that holds manifests alongside other YAML.
+
+``load_manifest`` raises ``ManifestLoadError`` for any YAML it cannot parse
+as a manifest, including files that never claimed to be one. A caller
+walking a specs directory therefore has to answer a question the parser
+does not: was this file *aiming* to be a manifest and failing, or is it
+something else sharing the directory?
+
+Both wrong answers are real bugs, and both have happened:
+
+- Treat everything as a broken manifest, and a "computed over a subset"
+  caveat fires on every mixed-directory run. A caveat that always fires
+  stops being read.
+- Treat nothing as one, and a broken manifest drops out of a financial
+  figure or a set of measured SLOs without a word (opensrm-oh27,
+  opensrm-3470).
+
+Promoted here from ``nthlayer_workers.learn.retrospective`` once a third
+consumer appeared, so the call sites stop reaching into one another
+(opensrm-3470).
+"""
+
+from __future__ import annotations
+
+import unicodedata
+import warnings
+from pathlib import Path
+from typing import NamedTuple
+
+import yaml
+
+from nthlayer_common.manifest.models import is_valid_service_type
+from nthlayer_common.manifest.parser.v1 import is_srm_v1_format
+from nthlayer_common.manifest.parser.v2 import is_opensrm_v2_format
+
+
+class ManifestCollisionWarning(UserWarning):
+    """Two manifest files shared a stem, so one was not loaded [opensrm-xvwt].
+
+    A warning rather than a structlog event, because this is a LIBRARY.
+    nthlayer-common never calls structlog.configure, so the default
+    PrintLogger writes to STDOUT — measured — and a consumer CLI emitting
+    machine-readable output on stdout would have a human-formatted log line
+    interleaved into it. warnings go to stderr, are filterable by category,
+    and are the pattern this package already uses for an authoring mistake it
+    should flag loudly without rejecting: see TargetConventionWarning in
+    target_validation.py.
+
+    The STRUCTURED form of the same information is scan_manifest_files()'
+    return value, which is what a caller that wants to act on it should use.
+    """
+
+
+# One home for the wording, and it names the actual risk rather than the
+# mechanism: an operator does not care that two stems matched, they care that a
+# service they declared is not being measured.
+_COLLISION_HINT = (
+    "If they declare DIFFERENT services, rename one: the dropped file is not "
+    "being measured."
+)
+
+# Suffixes a manifest may carry. Both, always: `.yml` invisibility is the
+# same silent-subset failure as an uncounted parse error, reached by file
+# extension instead — the manifest is dropped and nothing says so.
+MANIFEST_SUFFIXES = (".yaml", ".yml")
+
+
+def _resolve_collision(group: list[Path]) -> tuple[Path, list[Path]]:
+    """Which of several same-stem manifests to keep, and which to report.
+
+    A separate named function so the rule can be exercised WITHOUT a
+    filesystem. The three-way case needs `svc.yaml` and `svc.YAML` to coexist,
+    which a case-insensitive filesystem cannot do — so a temp-directory
+    fixture skipped on macOS and ran in Linux CI, and the skip hid an
+    assertion that was wrong. See
+    tests/test_manifest_scan.py::test_collision_precedence_is_deterministic.
+
+    Three ranks, in order:
+
+    1. MANIFEST_SUFFIXES order IS the precedence, so the rule and the tuple
+       cannot drift apart. ``.yaml`` is what the ecosystem writes, and that is
+       counted rather than asserted: across nthlayer/demo and opensrm/spec,
+       46 manifests are ``.yaml`` and 0 are ``.yml`` or a case variant.
+    2. The EXACTLY-lowercase spelling beats a case variant. Without this rank
+       the name tiebreak kept ``svc.YAML`` over ``svc.yaml``, because
+       ``"svc.YAML" < "svc.yaml"`` in ASCII.
+    3. Name, so the choice is never filesystem-order dependent.
+
+    PRECONDITION: every path's case-folded suffix is in MANIFEST_SUFFIXES.
+    scan_manifest_files() guarantees it by filtering on the same key; a direct
+    caller that does not will get ValueError from .index(), which is the right
+    outcome for a programming error but is not a guard.
+    """
+    kept, *dropped = sorted(
+        group,
+        key=lambda p: (
+            MANIFEST_SUFFIXES.index(p.suffix.lower()),
+            0 if p.suffix == p.suffix.lower() else 1,
+            p.name,
+        ),
+    )
+    return kept, dropped
+
+
+class SuffixCollision(NamedTuple):
+    """One stem declared twice, once per manifest suffix [opensrm-xvwt].
+
+    NamedTuple rather than the @dataclass this package uses for models: these
+    two are a return shape, not a domain object — no validation, no behaviour,
+    and callers unpack them positionally.
+    """
+
+    stem: str
+    kept: Path
+    dropped: Path
+
+
+class ManifestScan(NamedTuple):
+    """What a directory scan found, and what it had to choose between."""
+
+    files: list[Path]
+    suffix_collisions: list[SuffixCollision]
+
+
+def scan_manifest_files(specs_dir: str | Path) -> ManifestScan:
+    """Manifest files under *specs_dir*, with same-stem collisions resolved.
+
+    A directory holding BOTH ``svc.yaml`` and ``svc.yml`` — the ordinary
+    result of an editor default changing, or two people adding the same
+    service — previously yielded both [opensrm-xvwt]. Neither is foreign
+    YAML, so foreign_yaml_reason() passes them and both parse, and the
+    consequences were silent in two places:
+
+    - measure's load_specs appended the service's SLOs twice, so
+      evaluate_slos wrote two verdicts per window for one service/SLO. Since
+      count_consecutive_breaches counts VERDICTS rather than windows, a
+      3-window hysteresis threshold was reached in 2 real windows or fewer.
+      A judgment SLO firing early is the same class of wrong as one that
+      never fires.
+    - observe's per-service SLO counts, and any budget arithmetic derived
+      from them, were inflated.
+
+    Nothing errored and nothing warned, because both files are valid
+    manifests.
+
+    ``.yaml`` wins, deterministically — it is the suffix the ecosystem
+    writes — with the name as tiebreak so the choice cannot vary by
+    filesystem order. The dropped path is RETURNED rather than only logged,
+    which is the same reason opensrm-3470 added a parse-failure report: this
+    is a partial view of the directory, and the operator reading SLO output
+    is who needs to know a manifest was set aside.
+
+    STEM, not parsed service name. Two files can declare the same service
+    under unrelated names, and scan.py deliberately does not parse — that is
+    what foreign_yaml_reason() exists to avoid. So this catches the common
+    shape the bead describes and not every possible duplicate; a caller that
+    needs the stronger property has to compare parsed names itself.
+    """
+    path = Path(specs_dir)
+    if not path.is_dir():
+        return ManifestScan([], [])
+
+    # `not p.is_dir()` rather than `p.is_file()`: excluding DIRECTORIES was
+    # the point — a directory named `foo.yaml` would be counted as a broken
+    # manifest by every caller. is_file() also excludes a dangling symlink,
+    # which silently drops a stale overlay link that previously reached
+    # load_manifest and was counted.
+    #
+    # Suffix compared case-folded: `.YAML` was excluded outright — never
+    # loaded, never counted, never logged — which is the silent-subset-by-
+    # extension failure MANIFEST_SUFFIXES exists to prevent, one case-fold
+    # away.
+    # This sort is now BELT-AND-BRACES, kept rather than removed. Both return
+    # values are re-sorted below and _resolve_collision sorts its own group, so
+    # removing it changes nothing — proven, not assumed: a differential over
+    # 4,000 random directory shapes x 3 orderings found zero output
+    # differences. It stays because iterdir order is arbitrary and a future
+    # reader should not have to re-derive that the rest of this function is
+    # order-independent.
+    candidates = sorted(
+        p
+        for p in path.iterdir()
+        if not p.is_dir() and p.suffix.lower() in MANIFEST_SUFFIXES
+    )
+
+    by_stem: dict[str, list[Path]] = {}
+    for candidate in candidates:
+        # NFC-normalised, for the same reason the suffix is case-folded: two
+        # spellings of one name must not become two services. APFS PRESERVES
+        # normalisation rather than enforcing it, so `café.yaml` written NFC
+        # and `café.yml` written NFD are two directory entries with different
+        # byte stems — visually one stem. Measured before this: both were
+        # returned and no collision reported, so the double-count this function
+        # exists to stop survived for any non-ASCII filename.
+        # The stem is NOT case-folded, deliberately, while the suffix is. A
+        # suffix is a format marker, so `.YAML` and `.yaml` mean the same
+        # thing; a stem is a name, and `SVC.yaml` beside `svc.yml` is two
+        # names an operator can tell apart. Both of the bead's shapes — an
+        # editor default changing, two people adding the same service — produce
+        # an IDENTICAL stem, so folding case here would merge files that were
+        # never one service to catch a case that does not occur.
+        by_stem.setdefault(
+            unicodedata.normalize("NFC", candidate.stem), []
+        ).append(candidate)
+
+    files: list[Path] = []
+    collisions: list[SuffixCollision] = []
+    for stem, group in by_stem.items():
+        if len(group) == 1:
+            files.append(group[0])
+            continue
+        kept, dropped = _resolve_collision(group)
+        files.append(kept)
+        collisions.extend(SuffixCollision(stem, kept, d) for d in dropped)
+
+    return ManifestScan(
+        sorted(files),
+        sorted(collisions, key=lambda c: (c.stem, c.dropped.name)),
+    )
+
+
+def iter_manifest_files(specs_dir: str | Path) -> list[Path]:
+    """Manifest files under ``specs_dir``, sorted, ONE PER STEM.
+
+    A lossy view of scan_manifest_files(): same files, collisions raised as a
+    ManifestCollisionWarning rather than returned. Its signature is fixed — three consumers in
+    nthlayer-workers call it — so the de-duplication had to arrive without one,
+    and that is why this exists alongside the fuller function rather than
+    instead of it. A caller that should SURFACE a set-aside file to an operator
+    wants scan_manifest_files().
+
+    IT WARNS ONCE PER PROCESS, NOT ONCE PER SCAN. Python's default filter
+    dedupes on (message, category, module, lineno), and with stacklevel=2 the
+    key is the CALLER's line — so a worker re-scanning the same directory every
+    window warns on the first window and is silent thereafter. Quieter, but an
+    operator who misses the first one never sees it again, which is why the
+    three consumers should move to scan_manifest_files() and surface the
+    collision themselves: opensrm-j9wq.
+
+    NOTHING DROPS SILENTLY, and that is not belt-and-braces: grouping is by
+    stem, so a collision can be two DIFFERENT services rather than a duplicate,
+    and dropping one of those without a trace is the silent-subset failure this
+    module exists to prevent (opensrm-oh27, opensrm-3470). See
+    scan_manifest_files() for the full argument.
+
+    Sorted so the order is stable across machines. That matters to any caller
+    that dedupes first-wins — learn/retrospective does; observe's spec_loader
+    does not, and whether it should is opensrm-3470's follow-up rather than a
+    property this function can assume.
+
+    Returns empty for a path that is not a directory rather than raising, so a
+    caller that wants its own error message for that case keeps the decision.
+    """
+    scan = scan_manifest_files(specs_dir)
+    for collision in scan.suffix_collisions:
+        warnings.warn(
+            f"{collision.dropped} was not loaded: it shares the stem "
+            f"'{collision.stem}' with {collision.kept.name}. "
+            f"{_COLLISION_HINT}",
+            ManifestCollisionWarning,
+            # 2 = this function's caller. Measured, not copied: a deeper value
+            # names scan.py itself, which tells the reader nothing about which
+            # directory scan produced it.
+            stacklevel=2,
+        )
+    return scan.files
+
+
+def foreign_yaml_reason(spec_file: str | Path) -> str | None:
+    """Why a file that failed to load should NOT count as a broken manifest.
+
+    Returns ``None`` when the file was aiming at being a manifest — so the
+    caller counts it — or a short reason when it plainly was not, so the
+    caller can drop it and log the reason rather than dropping it silently.
+
+    Evidence of intent is checked in three widening steps: the canonical
+    v1/v2 format predicates, so this cannot drift from what the parser
+    accepts; then a near miss on those headers, since a typo'd kind or a
+    drifted API group is an ordinary way a real manifest breaks; then the
+    body, since a bad merge or a mis-indent can strip the header while
+    leaving ``spec.service`` (as a *mapping*), ``spec.slos`` or
+    ``spec.outcomes`` intact.
+
+    ``spec.service`` as a mapping is what separates a headerless manifest
+    from a headerless OpenSLO document, which writes the same key as a
+    plain string. Anything unreadable or empty counts too — a syntax error
+    or a truncated write inside a specs directory is a deployment error
+    either way.
+
+    LIMIT, stated rather than deferred: this recovers intent only while
+    evidence of intent survives. A file that has lost both its header and
+    its body is indistinguishable in principle from any other headerless
+    YAML mapping — both are dicts with no apiVersion, no kind, no
+    ``spec.service``. No content heuristic separates those, and adding more
+    markers would not change it. For such a file this returns a reason, so
+    the caller can record it rather than drop it without trace — which is
+    what lets an investigator chasing a number that looks wrong pick the
+    trail back up.
+    """
+    path = Path(spec_file)
+    try:
+        data = yaml.safe_load(path.read_text())
+    except (OSError, ValueError, yaml.YAMLError):
+        # ValueError covers UnicodeDecodeError on non-UTF-8 bytes. Too
+        # malformed to inspect, so it counts. A read failing here where
+        # load_manifest's read succeeded also means the file moved
+        # underneath us, which is not evidence it was foreign.
+        return None
+
+    if not data:
+        # None (zero bytes, whitespace, comments) or an empty container. A
+        # truncated or interrupted write is precisely what the count exists
+        # for.
+        return None
+
+    if not isinstance(data, dict):
+        return f"top-level YAML is {type(data).__name__}, not a mapping"
+
+    # "service" at the top level is the legacy pre-apiVersion shape that
+    # load_manifest still accepts.
+    if is_opensrm_v2_format(data) or is_srm_v1_format(data) or "service" in data:
+        return None
+
+    api_version = data.get("apiVersion")
+    kind = data.get("kind")
+    near_miss = (
+        isinstance(api_version, str)
+        and (api_version.startswith("srm/") or "opensrm" in api_version)
+    ) or (
+        isinstance(kind, str)
+        and kind.startswith(("ServiceManifest", "ServiceReliabilityManifest"))
+    )
+    if near_miss:
+        return None
+
+    # Body recovery: a bad merge or a mis-indent can strip the header while
+    # leaving the body intact, and that is the common corruption.
+    #
+    # The key names differ by format, and getting them wrong makes this whole
+    # branch inert — which it was until opensrm-3470's edge-cases pass:
+    #   v1  spec.slos          a MAPPING of name -> config (parser/v1 does
+    #                          slos_data.items()), not a list
+    #   v2  spec.slo           a list of OpenSLO documents
+    #       spec.judgment_slo  a list
+    #       spec.service       a MAPPING; OpenSLO writes the same key as a
+    #                          plain string, which is what keeps OpenSLO out
+    #       spec.outcomes      a mapping
+    #   v1  spec.type          REQUIRED by parse_srm_v1 (v1.py:91), and
+    #                          checked against is_valid_service_type rather
+    #                          than "is a string": a Backstage catalog-info
+    #                          carries spec.type too (`service`, `library`),
+    #                          and counting those makes every Backstage
+    #                          Component in the directory a broken manifest
+    #   v2  spec.owner         REQUIRED by parse_opensrm_v2 (v2.py:104)
+    # spec.slos is accepted as either shape: v1 writes a mapping, and a
+    # partially-converted file is exactly the kind of thing that lands here.
+    #
+    # The required keys matter most: a file carrying the one key its format
+    # cannot be parsed without makes a stronger claim to being a manifest
+    # than any of the optional ones above. Checking only the optional keys
+    # was the same mistake as testing spec.slos for the wrong type —
+    # reasoning about shapes without asking what the parsers demand.
+    spec = data.get("spec")
+    if isinstance(spec, dict) and (
+        isinstance(spec.get("service"), dict)
+        or isinstance(spec.get("slos"), (dict, list))
+        or isinstance(spec.get("slo"), list)
+        or isinstance(spec.get("judgment_slo"), list)
+        or isinstance(spec.get("outcomes"), dict)
+        or is_valid_service_type(spec.get("type"))
+        or isinstance(spec.get("owner"), dict)
+    ):
+        return None
+
+    return f"no manifest markers (apiVersion={api_version!r}, kind={kind!r})"