altar-identity 0.1.0__tar.gz

altar_identity-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+*.pyc
+*~
+**/__pycache__/*
+*.swp
+.vscode/
+.idea/
+.DS_Store
+.env*
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+pytest.xml
+.hypothesis/
+.python-version
+.venv/
+.venv-*/
+*.egg-info/
+build/
+dist/
+site/
+*.sqlite3
+*.log
+
+# Generated variant indexes and datasets. The small canonical gene table is tracked.
+altar/altar/variants/data/ccres.dnatree
+altar/altar/variants/data/region_annotations.parquet
+altar/altar/variants/data/variants.pkl.gz
+altar/altar/variants/data/raw/
+

altar_identity-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Riya Sinha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

altar_identity-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: altar-identity
+Version: 0.1.0
+Summary: Dependency-free variant and content identity shared by Altar and its model runtimes
+Project-URL: Documentation, https://kundajelab.github.io/altar/
+Project-URL: Issues, https://github.com/kundajelab/altar/issues
+Project-URL: Repository, https://github.com/kundajelab/altar
+Author: Riya Sinha
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bioinformatics,genomics,variant-identity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# altar-identity
+
+`altar-identity` holds the identity rules that Altar core and every Altar model runtime must agree on. It uses
+only the Python standard library and supports Python 3.9 and later, so a runtime pinned to an older
+TensorFlow or PyTorch stack runs the same code as Altar core instead of keeping a copy.
+
+Most users do not install it directly: `altar` depends on it and re-exports the variant names from
+`altar.variants`, `altar.models`, and `altar.sources`.
+
+## Variant identity
+
+```python
+from altar_identity import VariantKey, canonical_chromosome, canonical_variant_id
+
+canonical_chromosome("MT")  # "chrM"
+canonical_variant_id("1", 10, "a", "t")  # "chr1:10:A:T"
+VariantKey.require_canonical("chr1:10:A:T")  # rejects aliases such as "1:10:A:T"
+```
+
+A key is `chromosome:position:REF:ALT` with a one-based position, and every field is ASCII. Surrounding ASCII
+whitespace is trimmed from each field; other whitespace and non-ASCII text raise `VariantIdentityError`, a
+`ValueError`, rather than being folded (an Arabic-Indic or full-width digit never becomes `1`).
+
+- **Chromosome.** The `chr` prefix is optional and case-insensitive. Primary chromosomes are normalized in any
+  case (`1`, `chr01`, `CHR1` → `chr1`; `M`, `MT` → `chrM`). Every other contig keeps its exact spelling after
+  the prefix (`CHRUn_KI270302v1` → `chrUn_KI270302v1`), because reference contig names are case-sensitive and
+  the key must match the name in the FASTA. The name uses the VCF contig-name characters: letters, digits, and
+  `!#$%&*+./;=?@^_|~-`, which exclude `:`.
+- **Position.** A positive `int`. In text (`VariantKey.parse`, variant files, and `parse_position` for other
+  readers) it is ASCII digits `[0-9]+`: `+5`, `1_000`, `1e3`, and non-ASCII digits are rejected, although
+  Python's `int()` accepts some of them.
+- **Alleles.** Uppercased, then `[ACGTN]+`, the VCF base alphabet for REF and a concrete ALT. Symbolic
+  (`<DEL>`), `*`, `.`, breakend, IUPAC-ambiguity and `-` alleles are rejected, and REF must differ from ALT.
+  `N` is allowed in the key; reference validation decides whether a keyed variant can be scored.
+
+The key does not left-align or trim indels, and it does not carry the genome build.
+
+## Variant files
+
+```python
+from altar_identity import batched, read_variants
+
+for batch in batched(read_variants("variants.tsv"), 1024):
+    ...
+```
+
+Altar writes the variants for a model container as a headerless, tab-separated UTF-8 file with the columns
+`chr`, `pos`, `ref`, `alt`, and `variant_id`. `read_variants` also accepts four columns, or any label in the
+fifth, and never uses the fifth column. Fields are never quoted: a `"` is an ordinary character, and a field
+cannot hold a tab or line break. A leading UTF-8 byte-order mark is ignored. The reader yields canonical
+`VariantKey` values, skips blank lines, and raises `VariantFileError` naming the file and line for a malformed
+row. By default a repeated `variant_id` is an
+error; pass `duplicates="skip"` to keep the first occurrence or `duplicates="allow"` to yield every row.
+`read_variant_rows` yields `VariantRow(line, key)` records instead, for callers that apply their own policy
+(for example, SNVs only) and need to report the offending line. An empty or blank-only file yields nothing.
+
+## Content identity
+
+```python
+from altar_identity import sha256_file, verify_file
+
+digest = sha256_file("weights.h5")  # "sha256:<64 lowercase hex>"
+verify_file("weights.h5", digest, label="weights")
+```
+
+A digest is `sha256:` followed by 64 lowercase hexadecimal digits and names the bytes of one regular file.
+`verify_file` raises `DigestMismatchError` when the bytes differ, and also when the path is missing or is a
+directory. Symlinks are followed. `parse_sha256_digest` and `is_sha256_digest` check the exact spelling, and
+`SHA256_DIGEST_PATTERN` is the same rule as an unanchored regular expression for schemas that embed it.
+
+A file that many tasks read, such as a reference genome on a shared volume, need not be hashed by every task.
+`verify_file(..., trust_record=True, record=True)` accepts a file whose verification record is current and
+writes a record after a successful hash. The record is a one-line file at `<path>.sha256-verified`:
+
+```text
+verified-file/1 sha256:<64 hex> size=<bytes> mtime=<seconds> ctime=<seconds> inode=<number>
+```
+
+Rewriting, replacing, truncating, or appending to the file changes a recorded value and invalidates the record.
+`has_verification_record`, `write_verification_record`, and `verification_record_line` are the primitives Altar
+core's `verify_file_digest`, its staging backends, and the runtimes share. Anyone who can write the storage
+can also forge a record, so do not trust records where bytes first arrive, such as a download.
+
+## Development
+
+```bash
+uv run --isolated --no-project --python 3.9 --with pytest --with-editable identity \
+    python -m pytest identity/tests
+```

altar_identity-0.1.0/README.md

@@ -0,0 +1,89 @@
+# altar-identity
+
+`altar-identity` holds the identity rules that Altar core and every Altar model runtime must agree on. It uses
+only the Python standard library and supports Python 3.9 and later, so a runtime pinned to an older
+TensorFlow or PyTorch stack runs the same code as Altar core instead of keeping a copy.
+
+Most users do not install it directly: `altar` depends on it and re-exports the variant names from
+`altar.variants`, `altar.models`, and `altar.sources`.
+
+## Variant identity
+
+```python
+from altar_identity import VariantKey, canonical_chromosome, canonical_variant_id
+
+canonical_chromosome("MT")  # "chrM"
+canonical_variant_id("1", 10, "a", "t")  # "chr1:10:A:T"
+VariantKey.require_canonical("chr1:10:A:T")  # rejects aliases such as "1:10:A:T"
+```
+
+A key is `chromosome:position:REF:ALT` with a one-based position, and every field is ASCII. Surrounding ASCII
+whitespace is trimmed from each field; other whitespace and non-ASCII text raise `VariantIdentityError`, a
+`ValueError`, rather than being folded (an Arabic-Indic or full-width digit never becomes `1`).
+
+- **Chromosome.** The `chr` prefix is optional and case-insensitive. Primary chromosomes are normalized in any
+  case (`1`, `chr01`, `CHR1` → `chr1`; `M`, `MT` → `chrM`). Every other contig keeps its exact spelling after
+  the prefix (`CHRUn_KI270302v1` → `chrUn_KI270302v1`), because reference contig names are case-sensitive and
+  the key must match the name in the FASTA. The name uses the VCF contig-name characters: letters, digits, and
+  `!#$%&*+./;=?@^_|~-`, which exclude `:`.
+- **Position.** A positive `int`. In text (`VariantKey.parse`, variant files, and `parse_position` for other
+  readers) it is ASCII digits `[0-9]+`: `+5`, `1_000`, `1e3`, and non-ASCII digits are rejected, although
+  Python's `int()` accepts some of them.
+- **Alleles.** Uppercased, then `[ACGTN]+`, the VCF base alphabet for REF and a concrete ALT. Symbolic
+  (`<DEL>`), `*`, `.`, breakend, IUPAC-ambiguity and `-` alleles are rejected, and REF must differ from ALT.
+  `N` is allowed in the key; reference validation decides whether a keyed variant can be scored.
+
+The key does not left-align or trim indels, and it does not carry the genome build.
+
+## Variant files
+
+```python
+from altar_identity import batched, read_variants
+
+for batch in batched(read_variants("variants.tsv"), 1024):
+    ...
+```
+
+Altar writes the variants for a model container as a headerless, tab-separated UTF-8 file with the columns
+`chr`, `pos`, `ref`, `alt`, and `variant_id`. `read_variants` also accepts four columns, or any label in the
+fifth, and never uses the fifth column. Fields are never quoted: a `"` is an ordinary character, and a field
+cannot hold a tab or line break. A leading UTF-8 byte-order mark is ignored. The reader yields canonical
+`VariantKey` values, skips blank lines, and raises `VariantFileError` naming the file and line for a malformed
+row. By default a repeated `variant_id` is an
+error; pass `duplicates="skip"` to keep the first occurrence or `duplicates="allow"` to yield every row.
+`read_variant_rows` yields `VariantRow(line, key)` records instead, for callers that apply their own policy
+(for example, SNVs only) and need to report the offending line. An empty or blank-only file yields nothing.
+
+## Content identity
+
+```python
+from altar_identity import sha256_file, verify_file
+
+digest = sha256_file("weights.h5")  # "sha256:<64 lowercase hex>"
+verify_file("weights.h5", digest, label="weights")
+```
+
+A digest is `sha256:` followed by 64 lowercase hexadecimal digits and names the bytes of one regular file.
+`verify_file` raises `DigestMismatchError` when the bytes differ, and also when the path is missing or is a
+directory. Symlinks are followed. `parse_sha256_digest` and `is_sha256_digest` check the exact spelling, and
+`SHA256_DIGEST_PATTERN` is the same rule as an unanchored regular expression for schemas that embed it.
+
+A file that many tasks read, such as a reference genome on a shared volume, need not be hashed by every task.
+`verify_file(..., trust_record=True, record=True)` accepts a file whose verification record is current and
+writes a record after a successful hash. The record is a one-line file at `<path>.sha256-verified`:
+
+```text
+verified-file/1 sha256:<64 hex> size=<bytes> mtime=<seconds> ctime=<seconds> inode=<number>
+```
+
+Rewriting, replacing, truncating, or appending to the file changes a recorded value and invalidates the record.
+`has_verification_record`, `write_verification_record`, and `verification_record_line` are the primitives Altar
+core's `verify_file_digest`, its staging backends, and the runtimes share. Anyone who can write the storage
+can also forge a record, so do not trust records where bytes first arrive, such as a download.
+
+## Development
+
+```bash
+uv run --isolated --no-project --python 3.9 --with pytest --with-editable identity \
+    python -m pytest identity/tests
+```

altar_identity-0.1.0/altar_identity/__init__.py

@@ -0,0 +1,75 @@
+# Copyright 2026 Riya Sinha
+"""Variant and content identity shared by Altar core and its model runtimes.
+
+This package has no dependencies and supports Python 3.9, so a runtime pinned to an older scientific stack
+builds variant IDs, reads Altar's variant files, and verifies staged files with the same code as Altar core.
+
+- ``VariantKey``, ``canonical_chromosome``, ``canonical_variant_id``, ``parse_position``: the canonical
+  ``chr:pos:REF:ALT`` key and its textual position rule.
+- ``read_variants``, ``read_variant_rows``, ``batched``: the headerless variant file Altar hands to a model container.
+- ``sha256_file``, ``verify_file``, ``parse_sha256_digest``: the ``sha256:<hex>`` identity of one regular file,
+  and the verification records that let many tasks share one hash of a staged file. ``SHA256_DIGEST_PATTERN``
+  is the one spelling of the digest rule, for schemas and patterns that embed it.
+"""
+
+from altar_identity.digest import (
+    SHA256_DIGEST_PATTERN,
+    SHA256_PREFIX,
+    VERIFICATION_RECORD_FORMAT,
+    VERIFICATION_RECORD_SUFFIX,
+    DigestMismatchError,
+    has_verification_record,
+    is_sha256_digest,
+    parse_sha256_digest,
+    sha256_file,
+    verification_record_line,
+    verify_file,
+    write_verification_record,
+)
+from altar_identity.tsv import (
+    VARIANT_FIELD_COUNTS,
+    DuplicatePolicy,
+    VariantFileError,
+    VariantRow,
+    batched,
+    read_variant_rows,
+    read_variants,
+)
+from altar_identity.variant import (
+    VariantIdentityError,
+    VariantKey,
+    canonical_chromosome,
+    canonical_variant_id,
+    parse_position,
+)
+
+
+__version__: str = "0.1.0"
+
+__all__ = [
+    "SHA256_DIGEST_PATTERN",
+    "SHA256_PREFIX",
+    "VARIANT_FIELD_COUNTS",
+    "VERIFICATION_RECORD_FORMAT",
+    "VERIFICATION_RECORD_SUFFIX",
+    "DigestMismatchError",
+    "DuplicatePolicy",
+    "VariantFileError",
+    "VariantIdentityError",
+    "VariantKey",
+    "VariantRow",
+    "__version__",
+    "batched",
+    "canonical_chromosome",
+    "canonical_variant_id",
+    "has_verification_record",
+    "is_sha256_digest",
+    "parse_position",
+    "parse_sha256_digest",
+    "read_variant_rows",
+    "read_variants",
+    "sha256_file",
+    "verification_record_line",
+    "verify_file",
+    "write_verification_record",
+]

altar_identity-0.1.0/altar_identity/digest.py

@@ -0,0 +1,186 @@
+# Copyright 2026 Riya Sinha
+"""Content identity for staged files: one ``sha256:<64 lowercase hex>`` digest per regular file.
+
+A digest names the bytes of exactly one regular file. Symlinks are followed. A path that is missing or is a
+directory fails verification the same way as a digest mismatch, because neither has the bytes the digest
+names; ship a multi-file resource as an archive and digest the archive.
+
+Verification records
+--------------------
+A file read by many tasks, such as a reference genome, need not be hashed by every task. A verification record
+is a one-line text file at the file's path plus ``VERIFICATION_RECORD_SUFFIX``::
+
+    verified-file/1 sha256:<64 hex> size=<bytes> mtime=<seconds> ctime=<seconds> inode=<number>
+
+It states that the bytes matched the digest and pins the file's size, whole-second modification and
+status-change times, and inode as they were then. Rewriting, replacing, truncating, or appending to the file
+changes at least one of those values, which invalidates the record. Altar core's ``verify_file_digest``, its
+shell verifier, and every runtime read and write this same line through this module.
+"""
+
+from __future__ import annotations
+import contextlib
+import hashlib
+import os
+import re
+import stat
+import time
+import uuid
+from pathlib import Path
+
+
+SHA256_PREFIX = "sha256:"
+SHA256_DIGEST_PATTERN = f"{SHA256_PREFIX}[0-9a-f]{{64}}"
+"""Unanchored regular expression for a canonical digest. Anchor it (``re.fullmatch``, or ``^...$`` in a schema)
+or embed it in a larger pattern, such as an image reference, instead of spelling the digest rule again."""
+VERIFICATION_RECORD_SUFFIX = ".sha256-verified"
+VERIFICATION_RECORD_FORMAT = "verified-file/1"
+_SHA256_DIGEST = re.compile(SHA256_DIGEST_PATTERN)
+_BUFFER_SIZE = 1024 * 1024
+_RECORD_MAX_BYTES = 512
+
+
+class DigestMismatchError(ValueError):
+    """A path does not hold the single regular file whose bytes a digest names."""
+
+
+def is_sha256_digest(value: object) -> bool:
+    """Return whether ``value`` is exactly ``sha256:`` followed by 64 lowercase hexadecimal digits."""
+    return isinstance(value, str) and _SHA256_DIGEST.fullmatch(value) is not None
+
+
+def parse_sha256_digest(value: str) -> str:
+    """Return ``value`` unchanged if it is a canonical SHA-256 digest; otherwise raise ``ValueError``.
+
+    The check is exact: no surrounding whitespace, no trailing newline, and no uppercase hexadecimal.
+    """
+    if not is_sha256_digest(value):
+        msg = f"expected sha256:<64 lowercase hex>, got {value!r}"
+        raise ValueError(msg)
+    return value
+
+
+def sha256_file(path: str | os.PathLike[str]) -> str:
+    """Return the ``sha256:<hex>`` digest of the bytes at ``path``, reading it in bounded chunks."""
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        for chunk in iter(lambda: handle.read(_BUFFER_SIZE), b""):
+            digest.update(chunk)
+    return f"{SHA256_PREFIX}{digest.hexdigest()}"
+
+
+def verification_record_line(digest: str, status: os.stat_result) -> str:
+    """Return the verification-record line for ``digest`` and a file's ``os.stat`` result.
+
+    ``int()`` of the float times matches the whole seconds ``stat -c %Y`` and ``%Z`` print for any file written
+    after 1970, so a shell verifier renders the same line.
+    """
+    return (
+        f"{VERIFICATION_RECORD_FORMAT} {digest} size={status.st_size} mtime={int(status.st_mtime)} "
+        f"ctime={int(status.st_ctime)} inode={status.st_ino}"
+    )
+
+
+def _record_path(path: str | os.PathLike[str]) -> Path:
+    return Path(f"{os.fspath(path)}{VERIFICATION_RECORD_SUFFIX}")
+
+
+def has_verification_record(path: str | os.PathLike[str], digest: str) -> bool:
+    """Return whether `path` is a regular file with a current verification record for `digest`.
+
+    The record must name `digest` and match the file's current size, modification time, status-change time,
+    and inode number. A missing, unreadable, or stale record returns `False`. Checking a record reads two
+    small pieces of metadata and never reads the file's bytes. Symlinks are followed.
+    """
+    try:
+        status = Path(path).stat()
+        if not stat.S_ISREG(status.st_mode):
+            return False
+        with _record_path(path).open("rb") as handle:
+            content = handle.read(_RECORD_MAX_BYTES)
+    except OSError:
+        return False
+    return content.decode("ascii", "replace").rstrip("\n") == verification_record_line(digest, status)
+
+
+def write_verification_record(path: str | os.PathLike[str], digest: str, before: os.stat_result) -> bool:
+    """Write a record for bytes that just matched `digest`. Returns whether a record was written.
+
+    `before` is the file's status from before it was hashed. No record is written if the file changed while it
+    was being hashed. No record is written either while the file's status-change second is still the current
+    second: a later change within that same second would leave every recorded value unchanged. The next check
+    after that second writes the record instead. The write is atomic and best effort. A directory the caller
+    cannot write only means the next check hashes the file again.
+    """
+    try:
+        after = Path(path).stat()
+    except OSError:
+        return False
+    line = verification_record_line(digest, after)
+    if line != verification_record_line(digest, before) or int(after.st_ctime) >= int(time.time()):
+        return False
+    record = _record_path(path)
+    temporary = record.with_name(f"{record.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp")
+    try:
+        temporary.write_text(f"{line}\n", encoding="ascii")
+        temporary.replace(record)
+    except OSError:
+        with contextlib.suppress(OSError):
+            temporary.unlink()
+        return False
+    return True
+
+
+def verify_file(
+    path: str | os.PathLike[str],
+    expected: str,
+    *,
+    label: str = "resource",
+    trust_record: bool = False,
+    record: bool = False,
+) -> bool:
+    """Raise ``DigestMismatchError`` unless ``path`` is one regular file whose bytes have digest ``expected``.
+
+    ``expected`` must be a canonical SHA-256 digest; a malformed one raises ``ValueError``. ``label`` names
+    the file in the error message.
+
+    By default the file is always hashed. With ``trust_record``, a current verification record accepts the file
+    without reading it, so a file staged once and read by many tasks is hashed once. With ``record``, a
+    successful hash writes a record for later checks. Anyone who can write the storage can also write a record,
+    so trust records only on storage whose writers you trust, and never where bytes first arrive (a download).
+
+    Returns ``True`` when the file was hashed and ``False`` when a record accepted it.
+    """
+    parse_sha256_digest(expected)
+    if trust_record and has_verification_record(path, expected):
+        return False
+    if not Path(path).is_file():
+        msg = (
+            f"{label} at {str(path)!r} is not a regular file; a sha256 digest covers the bytes of one file, "
+            "so ship a directory as an archive"
+        )
+        raise DigestMismatchError(msg)
+    before = Path(path).stat()
+    actual = sha256_file(path)
+    if actual != expected:
+        msg = f"{label} at {str(path)!r} has digest {actual}; expected {expected}"
+        raise DigestMismatchError(msg)
+    if record:
+        write_verification_record(path, expected, before)
+    return True
+
+
+__all__ = [
+    "SHA256_DIGEST_PATTERN",
+    "SHA256_PREFIX",
+    "VERIFICATION_RECORD_FORMAT",
+    "VERIFICATION_RECORD_SUFFIX",
+    "DigestMismatchError",
+    "has_verification_record",
+    "is_sha256_digest",
+    "parse_sha256_digest",
+    "sha256_file",
+    "verification_record_line",
+    "verify_file",
+    "write_verification_record",
+]

altar_identity-0.1.0/altar_identity/tsv.py

@@ -0,0 +1,144 @@
+# Copyright 2026 Riya Sinha
+"""The canonical variant file that Altar hands to a model container.
+
+Altar core's scoring preparation writes each batch as a headerless, tab-separated UTF-8 file with one variant
+per line: ``chr``, ``pos`` (one-based), ``ref``, ``alt``, and the canonical ``variant_id``. The reader also
+accepts rows without the fifth column, and rows whose fifth column is any other label, because callers may
+hand a container a hand-written candidate file. The fifth column is never used: identity always comes from
+the locus fields.
+
+Core's scoring preparation reads its candidate files through this same reader, which applies ``VariantKey``'s
+field rules (see ``altar_identity.variant``). It trims fields and uppercases alleles, normalizes chromosome aliases
+(``1``, ``chr01`` and ``CHR1`` all become ``chr1``), and reads the position as ASCII digits. It rejects rows that
+have no canonical spelling, such as a contig containing ``:``, a position below one or written as ``+5`` or
+``1_000``, or an allele outside ``[ACGTN]``. Blank lines and a leading UTF-8 byte-order mark are skipped. Fields
+are never quoted: a ``"`` is an ordinary character, and a field cannot contain a tab, carriage return, or newline.
+"""
+
+from __future__ import annotations
+import csv
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal, NamedTuple, TypeVar
+
+from altar_identity.variant import VariantIdentityError, VariantKey, parse_position
+
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import Iterable, Iterator
+
+
+T = TypeVar("T")
+VARIANT_FIELD_COUNTS = frozenset({4, 5})
+DuplicatePolicy = Literal["error", "skip", "allow"]
+_DUPLICATE_POLICIES = frozenset({"error", "skip", "allow"})
+
+
+class VariantFileError(ValueError):
+    """A variant file row is malformed, has no canonical identity, or repeats a variant.
+
+    The message is ``path:line: reason``. ``line`` and ``reason`` are also attributes, so a caller that reports
+    errors in its own words (for example, without a temporary local path) need not parse the message.
+    """
+
+    def __init__(self, message: str, *, line: int | None = None, reason: str | None = None) -> None:
+        super().__init__(message)
+        self.line = line
+        self.reason = message if reason is None else reason
+
+
+def _row_error(path: str | os.PathLike[str], line: int, reason: str) -> VariantFileError:
+    return VariantFileError(f"{path}:{line}: {reason}", line=line, reason=reason)
+
+
+class VariantRow(NamedTuple):
+    """One canonical variant and the one-based file line it was read from."""
+
+    line: int
+    key: VariantKey
+
+
+def _fields(handle: Iterable[str], path: str | os.PathLike[str]) -> Iterator[tuple[int, list[str]]]:
+    """Yield ``(line, fields)`` for each non-blank row, split on tabs with no quoting."""
+    # No quoting: a `"` is an ordinary character, so one stray quote cannot swallow the lines after it.
+    reader = csv.reader(handle, delimiter="\t", quoting=csv.QUOTE_NONE)
+    while True:
+        try:
+            row = next(reader)
+        except StopIteration:
+            return
+        except csv.Error as error:
+            raise _row_error(path, reader.line_num, f"unreadable row: {error}") from error
+        if row:
+            yield reader.line_num, row
+
+
+def read_variants(path: str | os.PathLike[str], *, duplicates: DuplicatePolicy = "error") -> Iterator[VariantKey]:
+    """Stream canonical ``VariantKey`` values from a headerless ``chr pos ref alt [label]`` file.
+
+    ``duplicates`` sets what happens when two rows have the same canonical ``variant_id``: ``"error"``
+    (the default) raises ``VariantFileError``, ``"skip"`` yields only the first, and ``"allow"`` yields every
+    row. Core's scoring preparation never writes a variant twice. Errors name the file and line.
+    """
+    for row in read_variant_rows(path, duplicates=duplicates):
+        yield row.key
+
+
+def read_variant_rows(path: str | os.PathLike[str], *, duplicates: DuplicatePolicy = "error") -> Iterator[VariantRow]:
+    """Stream ``VariantRow(line, key)`` records, as ``read_variants`` does, for callers that report lines.
+
+    A runtime that applies its own policy to each variant (for example, SNVs only) uses the line to name the
+    offending row in its error, in the same ``path:line`` form as this reader's errors.
+    """
+    if duplicates not in _DUPLICATE_POLICIES:
+        msg = f"duplicates must be one of {sorted(_DUPLICATE_POLICIES)}, got {duplicates!r}"
+        raise ValueError(msg)
+    seen: set[str] = set()
+    # `utf-8-sig` drops a leading byte-order mark, which would otherwise become part of the first contig name.
+    with Path(path).open(newline="", encoding="utf-8-sig") as handle:
+        for line, row in _fields(handle, path):
+            if len(row) not in VARIANT_FIELD_COUNTS:
+                reason = f"expected 4 or 5 tab-separated fields (chr, pos, ref, alt[, label]), got {len(row)}"
+                raise _row_error(path, line, reason)
+            chromosome, raw_position, reference, alternate = row[:4]
+            try:
+                position = parse_position(raw_position)
+            except VariantIdentityError as error:
+                raise _row_error(path, line, f"invalid position {raw_position!r}") from error
+            try:
+                key = VariantKey.from_fields(chromosome, position, reference, alternate)
+            except VariantIdentityError as error:
+                raise _row_error(path, line, str(error)) from error
+            if duplicates != "allow":
+                if key.variant_id in seen:
+                    if duplicates == "skip":
+                        continue
+                    raise _row_error(path, line, f"contains duplicate variant_id {key.variant_id!r}")
+                seen.add(key.variant_id)
+            yield VariantRow(line, key)
+
+
+def batched(values: Iterable[T], size: int) -> Iterator[tuple[T, ...]]:
+    """Yield consecutive tuples of at most ``size`` items without reading ahead of the current batch."""
+    if isinstance(size, bool) or not isinstance(size, int) or size < 1:
+        msg = f"batch size must be a positive integer, got {size!r}"
+        raise ValueError(msg)
+    batch: list[T] = []
+    for value in values:
+        batch.append(value)
+        if len(batch) == size:
+            yield tuple(batch)
+            batch = []
+    if batch:
+        yield tuple(batch)
+
+
+__all__ = [
+    "VARIANT_FIELD_COUNTS",
+    "DuplicatePolicy",
+    "VariantFileError",
+    "VariantRow",
+    "batched",
+    "read_variant_rows",
+    "read_variants",
+]