aver-core 0.1.0__tar.gz

aver_core-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: aver-core
+Version: 0.1.0
+Summary: Aver domain models, RFC 8785 canonical JSON and hashing (PRD §11). Arrives in M0.
+License-Expression: Apache-2.0
+Requires-Dist: pydantic>=2.9,<3
+Requires-Python: >=3.11

aver_core-0.1.0/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "aver-core"
+version = "0.1.0"
+description = "Aver domain models, RFC 8785 canonical JSON and hashing (PRD §11). Arrives in M0."
+requires-python = ">=3.11"
+license = "Apache-2.0"
+dependencies = ["pydantic>=2.9,<3"]
+
+[build-system]
+requires = ["uv_build>=0.8,<0.13"]
+build-backend = "uv_build"

aver_core-0.1.0/pyproject.toml.orig

@@ -0,0 +1,11 @@
+[project]
+name = "aver-core"
+version = "0.1.0"
+description = "Aver domain models, RFC 8785 canonical JSON and hashing (PRD §11). Arrives in M0."
+requires-python = ">=3.11"
+license = "Apache-2.0"
+dependencies = ["pydantic>=2.9,<3"]
+
+[build-system]
+requires = ["uv_build>=0.8,<0.13"]
+build-backend = "uv_build"

aver_core-0.1.0/src/aver_core/__init__.py

@@ -0,0 +1,28 @@
+"""Aver core: domain models (PRD §11), RFC 8785 canonical JSON and hashing."""
+
+from .canonical import CanonicalizationError, canonical_bytes, canonical_json, parse_json
+from .hashing import (
+    GENESIS_HASH,
+    audit_entry_hash,
+    content_hash,
+    run_cache_key,
+    sha256_file,
+    sha256_hex,
+)
+from .samples import NotAReferenceSampleError, resolve_reference_sample, resolve_somatic_samples
+
+__all__ = [
+    "GENESIS_HASH",
+    "CanonicalizationError",
+    "NotAReferenceSampleError",
+    "audit_entry_hash",
+    "canonical_bytes",
+    "canonical_json",
+    "content_hash",
+    "parse_json",
+    "resolve_reference_sample",
+    "resolve_somatic_samples",
+    "run_cache_key",
+    "sha256_file",
+    "sha256_hex",
+]

aver_core-0.1.0/src/aver_core/canonical.py

@@ -0,0 +1,138 @@
+"""RFC 8785 JSON Canonicalization Scheme (JCS).
+
+Must agree byte for byte with apps/web/src/lib/hash.ts on the shared vectors in
+tests/golden/jcs (invariant 4). Values JSON cannot represent raise instead of
+being coerced, so a hash never covers silently altered data.
+
+Accepted: None, bool, str, int within +/-(2**53 - 1), finite float, list/tuple,
+dict with str keys. Anything else (Decimal, datetime, bytes, sets...) raises:
+convert it explicitly before hashing.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from decimal import Decimal
+from typing import Any
+
+MAX_SAFE_INTEGER = 2**53 - 1
+
+_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
+class CanonicalizationError(TypeError):
+    """Raised for values that have no RFC 8785 representation."""
+
+
+def canonical_json(value: Any) -> str:
+    """Serialise `value` as RFC 8785 canonical JSON text."""
+    out: list[str] = []
+    _write(value, out)
+    return "".join(out)
+
+
+def canonical_bytes(value: Any) -> bytes:
+    """Canonical JSON encoded as UTF-8: the exact bytes that get hashed."""
+    return canonical_json(value).encode("utf-8")
+
+
+def parse_json(text: str | bytes) -> Any:
+    """Parse JSON with ECMAScript number semantics (every number is a double).
+
+    Integers within the safe range stay `int` (their canonical text is
+    identical); larger integer literals become `float`, as JSON.parse would.
+    Use this, not json.loads, when re-canonicalising a document from elsewhere.
+    """
+    import json
+
+    def _int(s: str) -> int | float:
+        i = int(s)
+        return i if abs(i) <= MAX_SAFE_INTEGER else float(s)
+
+    return json.loads(text, parse_int=_int)
+
+
+def _write(value: Any, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, str):
+        out.append(_string(value))
+    elif isinstance(value, int):
+        if abs(value) > MAX_SAFE_INTEGER:
+            raise CanonicalizationError(f"integer {value} exceeds IEEE 754 safe range")
+        out.append(str(value))
+    elif isinstance(value, float):
+        out.append(_number(value))
+    elif isinstance(value, Mapping):
+        items = []
+        for k, v in value.items():
+            if not isinstance(k, str):
+                raise CanonicalizationError(f"object key {k!r} is not a string")
+            items.append((k, v))
+        # RFC 8785 §3.2.3: sort by UTF-16 code units (UTF-16BE bytes sort identically).
+        items.sort(key=lambda kv: kv[0].encode("utf-16-be", "surrogatepass"))
+        out.append("{")
+        for i, (k, v) in enumerate(items):
+            if i:
+                out.append(",")
+            out.append(_string(k))
+            out.append(":")
+            _write(v, out)
+        out.append("}")
+    elif isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray)):
+        out.append("[")
+        for i, v in enumerate(value):
+            if i:
+                out.append(",")
+            _write(v, out)
+        out.append("]")
+    else:
+        hint = " (convert Decimal explicitly)" if isinstance(value, Decimal) else ""
+        raise CanonicalizationError(f"{type(value).__name__} is not representable in JSON{hint}")
+
+
+def _string(s: str) -> str:
+    """JSON string as ECMAScript JSON.stringify writes it (well-formed variant)."""
+    parts = ['"']
+    for ch in s:
+        esc = _ESCAPES.get(ch)
+        if esc is not None:
+            parts.append(esc)
+        elif ch < " " or 0xD800 <= ord(ch) <= 0xDFFF:
+            parts.append(f"\\u{ord(ch):04x}")  # controls and lone surrogates
+        else:
+            parts.append(ch)
+    parts.append('"')
+    return "".join(parts)
+
+
+def _number(x: float) -> str:
+    """ECMAScript Number::toString for a finite double (RFC 8785 §3.2.2.3)."""
+    if not math.isfinite(x):
+        raise CanonicalizationError(f"{x} is not representable in JSON")
+    if x == 0:
+        return "0"  # also -0
+    sign = "-" if x < 0 else ""
+    # repr() yields the shortest digit string that round-trips, as ECMAScript requires.
+    d = Decimal(repr(abs(x)))
+    t = d.as_tuple()
+    digits = "".join(map(str, t.digits)).rstrip("0") or "0"
+    exponent = int(t.exponent)  # always an int for a finite value
+    k = len(digits)
+    n = exponent + len(t.digits)  # value = 0.digits * 10**n
+    if k <= n <= 21:
+        body = digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        body = digits[:n] + "." + digits[n:]
+    elif -6 < n <= 0:
+        body = "0." + "0" * (-n) + digits
+    else:
+        e = n - 1
+        exp = f"e{'+' if e >= 0 else '-'}{abs(e)}"
+        body = (digits if k == 1 else digits[0] + "." + digits[1:]) + exp
+    return sign + body

aver_core-0.1.0/src/aver_core/containers.py

@@ -0,0 +1,107 @@
+"""Pinned container images and a minimal Docker runner (ADR-005, invariant 5).
+
+Every image is referenced by digest. Tags are kept only as a human-readable
+label; the digest is what runs and what is recorded on each result. Changing a
+digest is a reviewed change: a comparator change is itself a drift source
+(PRD §13.5).
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Image:
+    name: str
+    tag: str
+    digest: str  # sha256:...
+
+    @property
+    def ref(self) -> str:
+        return f"{self.name}@{self.digest}"
+
+    @property
+    def label(self) -> str:
+        return f"{self.name}:{self.tag}@{self.digest}"
+
+
+# Digests resolved 2026-09-24 from the registries (docker pull + RepoDigests).
+IMAGES: dict[str, Image] = {
+    "happy": Image(
+        "jmcdani20/hap.py", "v0.3.12", "sha256:0812d37e7210011e407914deb3da2094ec8258077b21d3211e694e5ca303b489"
+    ),
+    "samtools": Image(
+        "quay.io/biocontainers/samtools",
+        "1.24--h9dcdb79_1",
+        "sha256:a130447589651ed09252aa95a5e4f4132942cdb54d835d81a04a9a930d656561",
+    ),
+    "bcftools": Image(
+        "quay.io/biocontainers/bcftools",
+        "1.24--h487d631_1",
+        "sha256:08f357e20dcf8ca75c06027f66b181f4fd88019fea7959b69047ad1b12b08a0c",
+    ),
+    # Executes Snakemake pipelines (ADR-012). The tag matches SNAKEMAKE_VERSION in
+    # packages/resolver, so the engine that runs is the engine the snapshot records.
+    "snakemake": Image(
+        "snakemake/snakemake", "v9.27.0", "sha256:488d0de0ad0f471e85df3fe80e4ada9686d4492d14fae4ebc8102f7ba6e4f5f1"
+    ),
+    # SV benchmarking (M8.3): the tool the GIAB SV v0.6 README recommends.
+    # Digest resolved 2026-10-13 (docker pull + RepoDigests).
+    "truvari": Image(
+        "quay.io/biocontainers/truvari",
+        "4.2.2--pyhdfd78af_0",
+        "sha256:4f99c6d8738549467a8caf0b89df019f10d73fbd30cb9b89661b9cf82a322313",
+    ),
+}
+
+
+class ContainerError(RuntimeError):
+    def __init__(self, cmd: Sequence[str], code: int, tail: str) -> None:
+        super().__init__(f"container exited {code}: {shlex.join(cmd)}\n{tail}")
+        self.code = code
+        self.tail = tail
+
+
+def docker_run(
+    image: Image,
+    args: Sequence[str],
+    *,
+    mounts: Mapping[str | Path, str],
+    workdir: str = "/tmp",
+    network: bool = False,
+    env: Mapping[str, str] | None = None,
+    stdout: Path | None = None,
+) -> str:
+    """Run `args` in `image` (by digest) as the calling user.
+
+    Returns captured stdout unless `stdout` is given, in which case output is
+    written there. No network unless asked: reference data is fetched and
+    verified by Aver, never by the tool.
+    """
+    cmd = ["docker", "run", "--rm", "-e", "HOME=/tmp", "-w", workdir]
+    if hasattr(os, "getuid"):
+        cmd += ["--user", f"{os.getuid()}:{os.getgid()}"]
+    if not network:
+        cmd += ["--network=none"]
+    for k, v in (env or {}).items():
+        cmd += ["-e", f"{k}={v}"]
+    for host, target in mounts.items():
+        cmd += ["-v", f"{Path(host).resolve()}:{target}"]
+    cmd += [image.ref, *args]
+    if stdout is not None:
+        with open(stdout, "wb") as f:
+            p = subprocess.run(cmd, stdout=f, stderr=subprocess.PIPE, check=False)  # noqa: S603
+        out = ""
+    else:
+        p = subprocess.run(cmd, capture_output=True, check=False)  # noqa: S603
+        out = p.stdout.decode("utf-8", "replace")
+    if p.returncode != 0:
+        tail = "\n".join(p.stderr.decode("utf-8", "replace").splitlines()[-40:])
+        raise ContainerError(cmd, p.returncode, tail)
+    return out

aver_core-0.1.0/src/aver_core/hashing.py

@@ -0,0 +1,73 @@
+"""Content hashes used across Aver (PRD §11, §13.2, §15.1; invariant 4).
+
+All hashes are lowercase hex SHA-256. Anything structured is hashed over its
+RFC 8785 canonical JSON, never over ad hoc string concatenation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from .canonical import canonical_bytes, canonical_json
+
+GENESIS_HASH = "0" * 64
+"""prev_hash of the first audit entry (matches apps/web)."""
+
+
+def sha256_hex(data: bytes | str) -> str:
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: str | Path, chunk: int = 1 << 20) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while block := f.read(chunk):
+            h.update(block)
+    return h.hexdigest()
+
+
+def content_hash(value: Any) -> str:
+    """sha256 of the canonical JSON of `value`."""
+    return sha256_hex(canonical_bytes(value))
+
+
+def audit_entry_hash(prev_hash: str, entry_without_hashes: dict[str, Any]) -> str:
+    """F-60 / §11.8: sha256(prev_hash || canonical_json(entry_without_hashes))."""
+    if "prev_hash" in entry_without_hashes or "entry_hash" in entry_without_hashes:
+        raise ValueError("entry must not contain its own hash fields")
+    return sha256_hex(prev_hash + canonical_json(entry_without_hashes))
+
+
+def run_cache_key(
+    *,
+    snapshot_hash: str,
+    truth_set_id: str,
+    target_bed_sha256: str | None,
+    comparator_version: str,
+    reference_genome_sha256: str,
+    region: str | None = None,
+    stratifications: tuple[str, str, tuple[str, ...]] | None = None,
+) -> str:
+    """PRD §13.2 run cache key.
+
+    Same inputs as the PRD formula, hashed as canonical JSON with named fields
+    instead of bare concatenation, which is ambiguous at field boundaries.
+    `region` (for example 'chr20') is included because a subset run is a
+    different measurement. `stratifications` likewise, and only when requested (F-32).
+    """
+    fields: dict[str, object] = {
+        "snapshot_hash": snapshot_hash,
+        "truth_set_id": truth_set_id,
+        "target_bed_sha256": target_bed_sha256,
+        "comparator_version": comparator_version,
+        "reference_genome_sha256": reference_genome_sha256,
+        "region": region,
+    }
+    if stratifications:  # (set id, set release, names): absent when unused, so earlier keys stay valid
+        set_id, release, names = stratifications
+        fields["stratifications"] = {"set": set_id, "release": release, "names": list(names)}
+    return content_hash(fields)

aver_core-0.1.0/src/aver_core/ids.py

@@ -0,0 +1,19 @@
+"""UUIDv7 primary keys (PRD §11: time-ordered locality). RFC 9562 §5.7."""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+
+
+def uuid7(ms: int | None = None) -> uuid.UUID:
+    """48-bit Unix milliseconds, version 7, variant 10, 74 random bits."""
+    ts = int(time.time() * 1000) if ms is None else ms
+    rand = int.from_bytes(os.urandom(10), "big")
+    value = (ts & ((1 << 48) - 1)) << 80
+    value |= 0x7 << 76
+    value |= ((rand >> 62) & 0xFFF) << 64
+    value |= 0b10 << 62
+    value |= rand & ((1 << 62) - 1)
+    return uuid.UUID(int=value)

aver_core-0.1.0/src/aver_core/models.py

@@ -0,0 +1,259 @@
+"""Domain models mirroring PRD §11 (ADR-002 applied to identity).
+
+INVARIANT 1: there is no field anywhere for a patient identifier, clinical
+sample name or clinical annotation. `extra="forbid"` means unexpected fields
+are rejected rather than carried along. Do not add such a field.
+
+These are transport/domain models shared by the CLI, API and workers. The
+SQLAlchemy tables (M2) map onto them.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated, Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+Sha256 = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{64}$")]
+OciDigest = Annotated[str, StringConstraints(pattern=r"^sha256:[0-9a-f]{64}$")]
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, use_enum_values=True)
+
+
+# ───────────────────────────── Enums (§11) ─────────────────────────────
+
+
+class OrgRole(StrEnum):
+    owner = "owner"
+    admin = "admin"
+    bioinformatician = "bioinformatician"
+    approver = "approver"
+    viewer = "viewer"
+
+
+class WorkflowEngine(StrEnum):
+    nextflow = "nextflow"
+    snakemake = "snakemake"
+    wdl = "wdl"
+    manual = "manual"
+    dragen = "dragen"  # vendor configuration snapshotted from the replay JSON (ADR-013)
+
+
+class AssayType(StrEnum):
+    wgs = "wgs"
+    wes = "wes"
+    panel = "panel"
+    other = "other"
+
+
+class VariantDomain(StrEnum):
+    germline_small = "germline_small"
+    somatic_small = "somatic_small"
+    sv = "sv"
+    cnv = "cnv"
+
+
+class DependencyKind(StrEnum):
+    container = "container"
+    tool = "tool"
+    reference_genome = "reference_genome"
+    annotation_db = "annotation_db"
+    parameter = "parameter"
+    conda_env = "conda_env"
+    engine = "engine"
+
+
+class RunStatus(StrEnum):
+    queued = "queued"
+    preparing = "preparing"
+    running = "running"
+    comparing = "comparing"
+    summarising = "summarising"
+    succeeded = "succeeded"
+    failed = "failed"
+    cancelled = "cancelled"
+
+
+class RunTrigger(StrEnum):
+    manual = "manual"
+    commit = "commit"
+    digest_change = "digest_change"
+    refdata_change = "refdata_change"
+    scheduled = "scheduled"
+    api = "api"
+
+
+class ExecBackend(StrEnum):
+    lab_runner = "lab_runner"
+    hosted = "hosted"
+    cli = "cli"
+
+
+class VariantClass(StrEnum):
+    SNP = "SNP"
+    INDEL = "INDEL"
+    ALL = "ALL"
+    SV = "SV"  # structural variants ≥50bp, benchmarked with truvari (M8.3)
+
+
+class DriftSeverity(StrEnum):
+    informational = "informational"
+    documentation = "documentation"
+    review_required = "review_required"
+    revalidation_required = "revalidation_required"
+    critical = "critical"
+
+
+SEVERITY_RANK: dict[str, int] = {s.value: i for i, s in enumerate(DriftSeverity)}
+
+
+class DriftDisposition(StrEnum):
+    open = "open"
+    acknowledged = "acknowledged"
+    revalidated = "revalidated"
+    waived = "waived"
+    superseded = "superseded"
+
+
+class EvidenceStatus(StrEnum):
+    generating = "generating"
+    ready = "ready"
+    signed = "signed"
+    superseded = "superseded"
+    failed = "failed"
+
+
+# ───────────────────────────── Reference data (§11.3, global) ─────────────────────────────
+
+
+class ReferenceMaterial(Model):
+    code: str  # 'HG002'
+    common_name: str
+    provider: Literal["GIAB", "SEQC2"]
+    aliases: tuple[str, ...] = ()  # accepted VCF sample names, e.g. 'NA24385'
+
+
+class TruthSet(Model):
+    id: str  # stable catalogue id, e.g. 'giab-hg002-v4.2.1-grch38'
+    reference_material: str
+    release_version: str
+    genome_build: Literal["GRCh38", "GRCh37", "CHM13v2.0"]
+    status: Literal["published", "draft"]
+    vcf_uri: str
+    vcf_sha256: Sha256 | None
+    confident_bed_uri: str
+    confident_bed_sha256: Sha256 | None
+    upstream_md5: dict[str, str] = Field(default_factory=dict)
+    published: str | None = None
+
+
+class ReferenceGenome(Model):
+    id: str
+    build: str
+    variant_label: str  # 'no_alt_analysis_set'
+    fasta_uri: str
+    fasta_sha256: Sha256 | None
+    upstream_md5: dict[str, str] = Field(default_factory=dict)
+
+
+# ───────────────────────────── Snapshots (§11.2) ─────────────────────────────
+
+
+class Dependency(Model):
+    kind: DependencyKind
+    name: str
+    version: str | None = None
+    digest: str | None = None
+    source_uri: str | None = None
+    process_names: tuple[str, ...] = ()
+    is_pinned: bool = True
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowInfo(Model):
+    engine: WorkflowEngine
+    engine_version: str | None
+    repo_url: str | None
+    commit_sha: str | None
+    ref_name: str | None
+    entrypoint: str | None = None
+    profile: str | None = None
+
+
+class DependencySnapshot(Model):
+    """F-20. The hashed content excludes volatile fields (resolved_at)."""
+
+    workflow: WorkflowInfo
+    dependencies: tuple[Dependency, ...]
+    resolved_config: dict[str, Any]
+    resolver_version: str
+    snapshot_hash: Sha256
+    unpinned_count: int
+    resolved_at: datetime
+
+
+# ───────────────────────────── Benchmarking (§11.4) ─────────────────────────────
+
+
+class BenchmarkMetric(Model):
+    variant_class: VariantClass
+    filter: Literal["PASS", "ALL"]
+    stratification: str | None = None  # None = whole confident region
+    truth_total: int
+    truth_tp: int
+    truth_fn: int
+    query_total: int
+    query_fp: int
+    recall: float | None
+    precision: float | None
+    f_measure: float | None
+    extra: dict[str, str] = Field(default_factory=dict)
+
+
+class BenchmarkResult(Model):
+    """What a CLI or Runner reports: metrics and metadata only, never reads."""
+
+    reference_material: str
+    truth_set_id: str
+    genome_build: str
+    region: str | None
+    target_bed_sha256: Sha256 | None
+    comparator_image: str
+    comparator_version: str
+    command: str
+    metrics: tuple[BenchmarkMetric, ...]
+    snapshot_hash: Sha256 | None
+    cache_key: Sha256
+    completed_at: str  # RFC 3339 UTC, second precision; reports take their dates from here, never the clock
+
+
+# ───────────────────────────── Drift (§11.5, §14) ─────────────────────────────
+
+
+class FiredRule(Model):
+    rule_id: str
+    source: Literal["class_rule", "semver_rule", "digest_rule", "policy", "integrity"]
+    severity: DriftSeverity
+    reason: str
+
+
+class AuditEntry(Model):
+    """§11.8. entry_hash = sha256(prev_hash || canonical_json(entry without hashes))."""
+
+    seq: int
+    organization_id: UUID | None
+    actor: str
+    action: str
+    entity_type: str
+    entity_id: str | None
+    before: dict[str, Any] | None
+    after: dict[str, Any] | None
+    request_id: str | None
+    occurred_at: str  # RFC 3339 UTC, stored as text for byte-stable hashing
+    prev_hash: Sha256
+    entry_hash: Sha256

aver_core-0.1.0/src/aver_core/samples.py

@@ -0,0 +1,86 @@
+"""The no-patient-data guard (invariant 1, PRD §20.2 validation level).
+
+Every VCF that Aver compares or transmits must carry exactly one sample, and
+that sample's name must be a registered public reference material (or one of
+its registered aliases). Anything else aborts with a clear error, before any
+metric is computed.
+
+Pipelines that compose the read-group sample from several samplesheet columns
+(nf-core/sarek writes SM as "<patient>_<sample>") are accepted only when every
+underscore-separated part is itself a registered name for the same material,
+e.g. "HG002_HG002" or "HG002_NA24385". Nothing else is ever composed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .models import ReferenceMaterial
+
+
+class NotAReferenceSampleError(ValueError):
+    """The VCF does not belong to a registered public reference material."""
+
+
+def _accepted(material: ReferenceMaterial) -> set[str]:
+    return {material.code, *material.aliases}
+
+
+def _matches(name: str, accepted: set[str]) -> bool:
+    parts = name.split("_")
+    return name in accepted or (len(parts) > 1 and all(p in accepted for p in parts))
+
+
+def resolve_somatic_samples(
+    sample_names: Iterable[str], tumor: ReferenceMaterial, normal: ReferenceMaterial
+) -> tuple[str, ...]:
+    """The somatic form of the guard (M7, ADR-014 §4): one or two samples, every name a
+    registered name of the declared tumor/normal pair, with the tumor present.
+
+    Caller-generic names ("TUMOR"/"NORMAL") are rejected: they cannot prove the VCF is
+    reference-material-derived, and proving that is this guard's whole job. The error
+    never echoes an unrecognised name — it could itself be an identifier.
+    """
+    names = list(sample_names)
+    if not 1 <= len(names) <= 2:
+        raise NotAReferenceSampleError(
+            f"expected a one- or two-sample somatic VCF for {tumor.code}/{normal.code}, found {len(names)} samples"
+        )
+    if len(set(names)) != len(names):
+        raise NotAReferenceSampleError("the VCF names the same sample twice")
+    t, n = _accepted(tumor), _accepted(normal)
+    accepted = sorted(t | n)
+    for name in names:
+        if not _matches(name, t) and not _matches(name, n):
+            raise NotAReferenceSampleError(
+                f"a VCF sample is not a registered name of the {tumor.code}/{normal.code} pair "
+                f"(accepted names: {', '.join(accepted)}). Caller-generic names such as TUMOR/NORMAL "
+                "are not accepted; rename the samples (bcftools reheader) to the registered names. "
+                "Aver only processes public reference materials; the comparison was aborted."
+            )
+    if not any(_matches(name, t) for name in names):
+        raise NotAReferenceSampleError(
+            f"the VCF carries no sample named for the tumor material {tumor.code}; a somatic "
+            "comparison needs the tumor sample present."
+        )
+    return tuple(names)
+
+
+def resolve_reference_sample(sample_names: Iterable[str], expected: ReferenceMaterial) -> str:
+    """Return the matched sample name, or raise NotAReferenceSampleError.
+
+    The error message never echoes an unrecognised sample name, since that name
+    could itself be an identifier.
+    """
+    names = list(sample_names)
+    if len(names) != 1:
+        raise NotAReferenceSampleError(f"expected a single-sample VCF for {expected.code}, found {len(names)} samples")
+    accepted = {expected.code, *expected.aliases}
+    parts = names[0].split("_")
+    if names[0] not in accepted and not (len(parts) > 1 and all(p in accepted for p in parts)):
+        raise NotAReferenceSampleError(
+            f"VCF sample is not the registered reference material {expected.code} "
+            f"(accepted names: {', '.join(sorted(accepted))}). Aver only processes public "
+            "reference materials; the comparison was aborted."
+        )
+    return names[0]