seqforge 2026.7.1__py3-none-any.whl

seqforge/models/base.py

@@ -0,0 +1,100 @@
+"""Shared scalars, controlled vocabularies, and the ``Evidenced[T]`` three-truths carrier.
+
+These are the atoms every other model is built from. ``Evidenced[T]`` wraps every interpretive
+manifest field so a value never travels without its provenance.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Generic, Literal, TypeVar
+
+from pydantic import (
+    AfterValidator,
+    BaseModel,
+    ConfigDict,
+    Field,
+    PositiveInt,
+    StringConstraints,
+)
+
+
+def _reject_absolute_or_local(value: str) -> str:
+    """Reject absolute or local filesystem paths in a manifest URI.
+
+    A manifest URI is a relative path, a non-file scheme (``s3://``, ``gs://``, ``https://``,
+    ``sra:``), or a bare accession — never ``/abs``, ``~/x``, ``C:\\...``, a UNC ``\\\\host``, or a
+    ``file://`` absolute path.
+    """
+    bad = (
+        value.startswith(("/", "~"))
+        or value.startswith("file:///")
+        or (len(value) > 1 and value[1] == ":")  # Windows drive, e.g. C:\
+        or value.startswith("\\\\")  # UNC \\host\share
+    )
+    if bad:
+        raise ValueError(f"absolute/local path forbidden in a manifest URI: {value!r}")
+    return value
+
+
+# ---- scalars & controlled vocabulary ----
+Sha256 = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{64}$")]
+"""Lowercase 64-hex sha256 digest (of file bytes, canonical text, or a bounded content key)."""
+
+Uri = Annotated[str, StringConstraints(min_length=1), AfterValidator(_reject_absolute_or_local)]
+"""A manifest URI: relative path / non-file scheme / bare accession. Never an absolute local path."""
+
+LocalPath = Annotated[str, StringConstraints(min_length=1)]
+"""An internal-only local filesystem path (e.g. where probe read bytes). Never enters a Manifest."""
+
+AssayTerm = Annotated[str, StringConstraints(pattern=r"^(EFO|OBI):\d{4,}$")]
+"""EFO/OBI assay CURIE, e.g. ``EFO:0009922``."""
+
+NcbiTaxid = PositiveInt
+"""NCBI taxonomy id, e.g. 9606, 10090, 559292, 6239."""
+
+Accession = Annotated[
+    str,
+    StringConstraints(pattern=r"^([SED]R[RXPS]\d+|GS[EM]\d+|PRJ[A-Z]{2}\d+|SAM[NED][A-Z]?\d+)$"),
+]
+"""NCBI/ENA/DDBJ run/experiment/study/sample, GEO, BioProject, or BioSample accession."""
+
+ChemistryId = str
+"""KB primary key, e.g. ``10x-3p-gex-v3``. Open vocabulary, validated against the KB in code."""
+
+Confidence = Annotated[float, Field(ge=0.0, le=1.0)]
+Rung = Annotated[int, Field(ge=0, le=7)]
+Basis = Literal["observed", "asserted", "inferred", "user_confirmed"]
+
+
+T = TypeVar("T")
+
+
+class Evidenced(BaseModel, Generic[T]):
+    """A single manifest field value tagged with its epistemic provenance.
+
+    Wraps every interpretive manifest field. ``basis`` records how we know it
+    (``observed`` from bytes, ``asserted`` from humans/DBs, ``inferred`` derived,
+    ``user_confirmed``); disagreement across bases becomes a first-class ``Conflict``, never a
+    silent merge. ``rung`` is the cheapest escalation-ladder step that settled the field.
+
+    ``confidence`` is **optional, and ``None`` is the informative value**: it means no judgement was
+    made, so there is no confidence to report. Copying a ``strain = CQ758`` out of a BioSample record
+    involves no interpretation — the record says it, we transcribed it, and ``basis="asserted"`` plus
+    the record accession in ``evidence`` already says everything true about how we know it. Writing
+    ``1.0`` there would invite exactly the question it cannot answer ("you are certain the strain is
+    CQ758?"); we are certain the *record declares* it, which is a different claim and the one we make.
+
+    So: a number here means somebody or something weighed evidence and could have been wrong. That is
+    the winning candidate's score, or a language model's advisory self-report on reading prose. It is
+    never a decoration, and it is never copied from a neighbouring field — a value repeated across
+    four fields is one judgement wearing four hats, which is the ``processing``-masquerading-as-a-truth
+    mistake in miniature.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    value: T
+    basis: Basis
+    evidence: list[str] = Field(default_factory=list)
+    confidence: Confidence | None = None
+    rung: Rung

seqforge/models/blocker.py

@@ -0,0 +1,71 @@
+"""``Blocker`` — refusal as an exit code.
+
+A ``Blocker`` is ALWAYS fatal (its presence => nonzero exit). Advisory diagnostics are a separate
+:class:`ValidationWarning` (renamed from the design's ``Warning`` to avoid shadowing the builtin), so
+branching code never inspects a severity to decide whether something blocks.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class BlockerCode(StrEnum):
+    """The stable contract the CLI/skill branch on."""
+
+    MISSING_TECHNICAL_READ = "MISSING_TECHNICAL_READ"
+    #: The winning barcoded chemistry's barcode role IS filled, but no seated read carries
+    #: whitelist-matchable barcodes though the chemistry declares a whitelist — STARsolo would read
+    #: barcodes from a read that matches nothing and report ~0 valid barcodes at exit 0. Distinct from
+    #: MISSING_TECHNICAL_READ, where the role is structurally UNFILLABLE (no read of the right shape).
+    BARCODE_READ_ABSENT = "BARCODE_READ_ABSENT"
+    TRUNCATED_GZIP = "TRUNCATED_GZIP"
+    CORRUPT_FASTQ = "CORRUPT_FASTQ"
+    UNSUPPORTED_TECHNOLOGY = "UNSUPPORTED_TECHNOLOGY"
+    PRETRIMMED_VARIABLE_LENGTH = "PRETRIMMED_VARIABLE_LENGTH"
+    NO_VALID_ROLE_ASSIGNMENT = "NO_VALID_ROLE_ASSIGNMENT"
+    ONLIST_VERIFICATION_FAILED = "ONLIST_VERIFICATION_FAILED"
+    UNRESOLVED_CONFLICT = "UNRESOLVED_CONFLICT"
+    MISSING_CONTROLLED_VOCAB = "MISSING_CONTROLLED_VOCAB"
+    ABSOLUTE_PATH = "ABSOLUTE_PATH"
+    #: A processing manifest's genome does not belong to the dataset's organism. A wrong-but-VALID
+    #: assembly is the most catastrophic silent failure available here: it aligns, exits 0, and emits
+    #: a plausible matrix in the wrong coordinate space. Nothing downstream would ever notice.
+    GENOME_ORGANISM_MISMATCH = "GENOME_ORGANISM_MISMATCH"
+    #: A processing manifest bound to a different dataset than the one being compiled.
+    DATASET_PIN_MISMATCH = "DATASET_PIN_MISMATCH"
+    #: An archive record was supplied and does not account for the files on disk. Only ever raised
+    #: when a record EXISTS: a dataset with no accession has nothing to join and is not a refusal.
+    #: Half-joining is the failure this exists to prevent — the files it could not place would get no
+    #: sample facts, and a manifest that is confidently right about four samples and silent about two
+    #: reads as a manifest about six.
+    RECORD_JOIN_INCOMPLETE = "RECORD_JOIN_INCOMPLETE"
+
+
+class BlockerSubject(BaseModel):
+    """What the refusal is about. ``ref`` is a basename / dotted path / dataset id — never a path."""
+
+    kind: Literal["file", "field", "dataset"]
+    ref: str
+
+
+class Blocker(BaseModel):
+    """A structured refusal emitted alongside a nonzero exit. ``remedy`` MUST be actionable."""
+
+    id: str
+    code: BlockerCode
+    message: str
+    remedy: str
+    subject: BlockerSubject
+    evidence: list[str] = Field(default_factory=list)
+
+
+class ValidationWarning(BaseModel):
+    """A non-blocking advisory note (exits 0). Kept distinct from :class:`Blocker`, which is fatal."""
+
+    code: str
+    message: str
+    subject: BlockerSubject

seqforge/models/conflict.py

@@ -0,0 +1,47 @@
+"""``Conflict`` — a surfaced disagreement between truths, never auto-picked.
+
+``positions`` generalizes the common observed/asserted pair; ``status="benign"`` is the §12 escape
+hatch for two confusable KB entries that emit identical ``backend.params``.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from .base import Basis, Confidence, Rung
+
+Decidable = Literal["reads", "onlist", "metadata", "alignment", "user"]
+"""How a divergent pair could be separated. Includes ``onlist`` — the rung-3 mechanism §12 uses."""
+
+
+class ConflictPosition(BaseModel):
+    """One side of a disagreement. ``value`` is the canonical string form (fields are heterogeneous)."""
+
+    value: str
+    basis: Basis
+    evidence: list[str] = Field(default_factory=list)
+    confidence: Confidence
+
+
+class Resolution(BaseModel):
+    """How an open conflict was ultimately settled."""
+
+    chosen_value: str
+    basis: Basis
+    rung: Rung
+    decided_by: Literal["code", "user", "benign_equivalence"]
+    note: str | None = None
+
+
+class Conflict(BaseModel):
+    """A first-class, surfaced disagreement between truths."""
+
+    id: str
+    field: str
+    positions: list[ConflictPosition] = Field(min_length=2)
+    kind: Literal["observed_vs_asserted", "asserted_vs_asserted", "other"]
+    decidable_by: list[Decidable]
+    status: Literal["open", "resolved", "benign"] = "open"
+    resolution: Resolution | None = None

seqforge/models/dataset.py

@@ -0,0 +1,320 @@
+""":class:`DatasetManifest` — a finished assay. Two truths, one lifetime, IMMUTABLE.
+
+``library`` is physical truth about molecules and sequencer output (authority = **evidence**);
+``experiment`` is biological/metadata truth (authority = **metadata and humans**). Both are claims
+about *what the data is*. A finished assay does not change, so neither does this file: it is
+content-addressed, and nothing downstream may write to it. When a new fact arrives, the manifest is
+rebuilt from evidence and gets a new hash. It is never patched.
+
+**What is deliberately absent is the point.** There is no ``processing`` section here. What we choose
+to *do* with an assay is intent, not truth, and it lives in
+:mod:`~seqforge.models.processing` — of which there are many per dataset. The old three-section
+manifest made "three truths" (the three *bases*) and "three sections" line up by coincidence, and the
+pun cost us: ``processing`` inherited the grammar of a truth — ``Evidenced`` fields, an "authority", a
+uniform ``basis="inferred"`` stamped on by construction — and then ``compose`` read almost none of
+them. A field that is never read can never produce the ``Conflict`` the three-truths rule promises. ``base.py`` listing
+**four** bases against three sections was the tell.
+
+This module imports nothing from ``processing``, and must not. That independence is the two-artifact
+split expressed as an import graph: a dataset cannot know how it will be processed, because it will be
+processed many ways.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from .base import Accession, AssayTerm, ChemistryId, Evidenced, Sha256, Uri
+from .evidenced import (
+    EvidencedAccessionList,
+    EvidencedChemistrySet,
+    EvidencedStr,
+    EvidencedTaxid,
+)
+
+
+class ReadAnchor(BaseModel):
+    """A floating element's addressing, carried into the IR so the manifest records what STAGGERS.
+
+    A fixed element has a ``start``; an anchored one does not — its position floats per read (BD
+    Rhapsody Enhanced's 0-3 bp diversity insert shifts every cell-label block downstream). The manifest
+    is *what the data is*, so it must say an element floats rather than pin it to a wrong constant. This
+    mirrors the KB DSL's ``kb.schema.Anchor`` field-for-field (``test_read_anchor_mirrors_the_kb_anchor``
+    keeps the two from drifting); it is duplicated rather than imported because the IR is the
+    schema-export source of truth and must not pull the ``kb``->``probe``->``models`` import chain back
+    into ``models``. It carries no interpretation, so it is a plain ``BaseModel``, not ``Evidenced``.
+    """
+
+    relative_to: Literal["read_start", "read_end", "element"] = "read_start"
+    ref_element: str | None = None
+    ref_side: Literal["start", "end"] = "end"
+    offset: int = 0
+    motif: str | None = None
+    max_mismatch: int = 0
+
+
+class ReadElement(BaseModel):
+    """One ordered sub-region of a read; a superset/adapter over a seqspec Region.
+
+    Adds a derived ``start`` and an interpretive ``role`` that seqspec Regions do not carry. seqspec
+    ``sequence_type`` maps: fixed -> ``sequence``; random -> random ACGT; onlist -> ``onlist_ref``. An
+    ``anchor`` (with no fixed ``start``) marks an element whose position floats per read.
+    """
+
+    role: Literal["CB", "UMI", "cDNA", "gDNA", "index", "linker", "polyT", "polyA"]
+    region_type: Literal[
+        "barcode",
+        "umi",
+        "cdna",
+        "gdna",
+        "index5",
+        "index7",
+        "linker",
+        "poly_A",
+        "poly_t",
+        "custom_primer",
+    ]
+    start: int | None = None
+    length: int | None = None
+    min_len: int | None = None
+    max_len: int | None = None
+    sequence: str | None = None
+    onlist_ref: str | None = None
+    #: Present iff the element floats (no fixed ``start``); records the KB's declared anchor verbatim.
+    anchor: ReadAnchor | None = None
+
+
+class ReadDef(BaseModel):
+    """A sequencing read (== one FASTQ), aligned to a seqspec Read. ``read_id`` is a role, not a file."""
+
+    read_id: str
+    strand: Literal["pos", "neg"]
+    min_len: int = Field(ge=0)
+    max_len: int = Field(ge=0)
+    elements: list[ReadElement]
+
+
+class ReadLayout(BaseModel):
+    """Full physical library structure = ordered reads x ordered elements."""
+
+    modality: Literal["rna", "atac", "protein", "crispr", "dna"]
+    reads: list[ReadDef]
+
+
+class EvidencedReadLayout(Evidenced[ReadLayout]):
+    """An ``Evidenced`` read layout."""
+
+
+class Onlist(BaseModel):
+    """Barcode-whitelist registry entry; fetched via pooch + hash-verified, never vendored.
+
+    ``orientation_hint`` is a non-authoritative default; the authoritative orientation lives per-read
+    in the KB (one list can be forward for GEX and reverse-complemented for ATAC).
+    """
+
+    name: str
+    uri: Uri
+    sha256: Sha256
+    length: int = Field(ge=1)
+    orientation_hint: Literal["forward", "reverse_complement"] | None = None
+    n_entries: int | None = None
+
+
+class FileInventoryItem(BaseModel):
+    """One physical file + checksum + assigned role. No absolute path.
+
+    ``read_id`` is a plain string, not ``Evidenced``, and that is not a demotion. The role assignment
+    and the chemistry come out of **one** joint optimization — ``Candidate`` is literally
+    ``(technology, score, role_assignment)``, and the score scores the pair — so the confidence in
+    "this file is R1" and the confidence in "this library is v3" are the same number, and
+    ``library.chemistry`` is where it lives. Twelve files each carrying a copy of it was the pilot's
+    manifest saying one thing thirteen times.
+    """
+
+    uri: Uri
+    basename: str
+    sha256: Sha256
+    size_bytes: int = Field(gt=0)
+    #: The read role the joint optimization assigned, e.g. ``R1``, or :data:`INDEX_ROLE` for a
+    #: technical sample-index read set aside from the pipeline. ``None`` = unassigned, which
+    #: ``validate`` surfaces: an unassigned file is one ``compose`` will silently skip.
+    read_id: str | None = None
+
+
+#: The ``read_id`` marking a technical sample-index read (10x I1/I2). STARsolo consumes only the
+#: CB+UMI and cDNA reads, so an 8/10 bp index file is a leftover of an *already-decided* run — set
+#: aside under this role rather than left unassigned (which blocks) or forced into a layout (which
+#: would demand an index file of every clean sample). It is not a layout read and never becomes a
+#: unit; the length gate that assigns it lives in ``resolve/engine.py`` (:func:`index_tagged_roles`).
+INDEX_ROLE = "index"
+
+
+class AssayLabel(BaseModel):
+    """One chemistry, spelled three ways: our key, EFO's id, and EFO's words.
+
+    This exists because ``assay: EFO:0009922`` beside ``chemistry: [10x-3p-gex-v3,
+    10x-3p-gex-v3.1]`` was two puzzles at once. *What is the difference between them?* — none, they
+    are the same fact in two vocabularies. *Why is one a list and the other not?* — because the
+    §12 equivalence class has two members and the assay field could only hold one, so it silently
+    dropped v3.1's CURIE.
+
+    Making it a label per chemistry answers both and removes a third problem nobody had noticed: an
+    assay CURIE that disagrees with the chemistry it names is now **inexpressible** rather than
+    merely absent. There is nowhere to write it.
+
+    ``name`` is EFO's own label, generated into ``io/efo/labels.json`` from EBI's OLS4. Never typed
+    here: a label we maintain by hand is a label that drifts from the ontology it claims to quote.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    #: The KB's primary key, e.g. ``10x-3p-gex-v3``.
+    chemistry: ChemistryId
+    #: The controlled-vocabulary id, e.g. ``EFO:0009922``.
+    curie: AssayTerm
+    #: What EFO calls it, e.g. ``10x 3' v3``. The thing a human reads.
+    name: str
+
+
+class LibrarySection(BaseModel):
+    """Physical truth. Authority = EVIDENCE.
+
+    **One decision, one confidence.** ``chemistry`` is the decision — the joint optimization over
+    (which technology, which file is which read) that ``resolve score`` performs — and it is the only
+    ``Evidenced`` field here. Everything else follows from it: ``assay`` is the same answer in EFO's
+    vocabulary, ``read_layout`` is the KB's declared structure for that chemistry filled in with
+    measured lengths, ``files[].read_id`` is the assignment half of the very same optimization, and
+    ``onlists`` are the whitelists that chemistry uses.
+
+    They used to each carry their own ``Evidenced`` envelope, and the pilot's manifest showed what
+    that bought: ``confidence: 0.750672`` printed four times, identical, because it was always one
+    number about one decision wearing four hats. Four envelopes cannot disagree — they were filled
+    from the same variable — so they were never four truths, and we never asked for four. We ask
+    that a value not travel without its provenance, which is exactly what one honest envelope does.
+    A field repeated is not provenance; it is decoration that looks like provenance, which is worse
+    than none.
+    """
+
+    chemistry: EvidencedChemistrySet
+    #: One per chemistry in the equivalence class, same order. Derived, so it carries no confidence.
+    assay: list[AssayLabel] = Field(default_factory=list)
+    read_layout: ReadLayout
+    onlists: list[Onlist] = Field(default_factory=list)
+    files: list[FileInventoryItem]
+
+
+class SampleGroup(BaseModel):
+    """One biological sample, the files that carry it, and what is declared about it.
+
+    ``attributes`` is keyed by an **NCBI harmonized BioSample attribute name** — ``strain``,
+    ``tissue``, ``dev_stage``, ``genotype``, all 960 of them — and the validator refuses anything
+    else. Two named fields (``tissue``, ``condition``) used to sit here instead, and both were wrong
+    in the same way:
+
+    - ``condition`` is not a vocabulary anyone else uses. We invented it, and a field named
+      "condition" accepts anything you can call a condition; on the pilot a language model filed worm
+      husbandry into it. NCBI's ``treatment`` / ``genotype`` / ``disease`` are the real keys, each
+      with a definition somebody else maintains.
+    - Two typed fields cannot hold ``strain``, and ``strain`` is the only structured field that
+      separates the pilot's wild-type samples from its daf-2 mutants.
+
+    An open dict rather than 960 pydantic fields, because a typed list mirroring somebody else's
+    vocabulary is the shape this repo keeps getting bitten by: it rots the moment they add an
+    attribute, and nothing goes red. The vocabulary is the file NCBI's list was generated into, and
+    the validator reads *it*.
+    """
+
+    sample_id: str
+    #: The archive's id for this sample, when there is one. ``None`` for a dataset that never went
+    #: near an archive — which is most of them, and not a defect.
+    accession: Accession | None = None
+    attributes: dict[str, EvidencedStr] = Field(default_factory=dict)
+    file_uris: list[Uri] = Field(default_factory=list)
+
+    @field_validator("attributes")
+    @classmethod
+    def _keys_are_ncbi_attributes(cls, value: dict[str, EvidencedStr]) -> dict[str, EvidencedStr]:
+        """Fail closed on a key NCBI does not define: no field enters a manifest unvalidated."""
+        from ..io.attributes import is_attribute
+
+        unknown = sorted(k for k in value if not is_attribute(k))
+        if unknown:
+            raise ValueError(
+                f"not NCBI harmonized BioSample attribute name(s): {unknown}. A sample attribute's "
+                f"key space is NCBI's 960 curated names (`seqforge io attributes list`), not ours."
+            )
+        return value
+
+
+class Study(BaseModel):
+    """The study these files came from, as the archive declares it.
+
+    Deliberately **not** ``Evidenced``: none of it is an interpretation. The record says the title is
+    X and we copied X, exactly as we copy a file's ``sha256``. The abstract is deliberately absent —
+    it is prose, it belongs in a document a quote can grep back into, and pasting a paragraph of
+    English into a content-addressed manifest would make the dataset's identity depend on it.
+    """
+
+    accession: Accession | None = None
+    title: str | None = None
+    center: str | None = None
+    data_type: str | None = None
+    released: str | None = None
+
+
+class ExperimentSection(BaseModel):
+    """Biological/metadata truth. Authority = METADATA + humans."""
+
+    organism: EvidencedTaxid
+    accessions: EvidencedAccessionList
+    samples: list[SampleGroup]
+    study: Study | None = None
+
+
+class DatasetProvenance(BaseModel):
+    """Binds a dataset manifest to the bytes and the KB that read them.
+
+    ``workflow_version`` is deliberately ABSENT. Nothing in ``library``/``experiment`` depends on
+    which Snakemake module will one day run: the assay happened before we had an opinion about it.
+    It belongs to the processing manifest, and folding it in here would make a dataset's identity
+    churn every time a rule file changed — which is exactly the coupling the two-artifact split removes.
+    """
+
+    dataset_hash: str
+    kb_version: str
+    seqforge_version: str
+
+
+class DatasetManifest(BaseModel):
+    """A finished assay: what the bench did. Two truths, two authorities, one lifetime.
+
+    Structural only: semantic cross-checks (referential integrity — every experiment ``file_uri`` in
+    the library inventory — and the no-absolute-path sweep) are enforced by ``manifest validate``
+    as ``Blocker``s, not as construction-time ``ValidationError``s.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    library: LibrarySection
+    experiment: ExperimentSection
+    provenance: DatasetProvenance
+
+
+__all__ = [
+    "ReadAnchor",
+    "ReadElement",
+    "ReadDef",
+    "ReadLayout",
+    "EvidencedReadLayout",
+    "Onlist",
+    "FileInventoryItem",
+    "AssayLabel",
+    "LibrarySection",
+    "SampleGroup",
+    "Study",
+    "ExperimentSection",
+    "DatasetProvenance",
+    "DatasetManifest",
+]

seqforge/models/evidenced.py

@@ -0,0 +1,54 @@
+"""Named ``Evidenced[T]`` specializations over the base scalars — stable ``$defs`` for schema export.
+
+Pydantic generics are structural: ``Evidenced[str]`` has no stable class name, so exporting it inlines
+an anonymous schema and the ``$defs`` churn every time an unrelated field moves. Naming each one keeps
+the exported JSON Schema (design §1.8, the single source of truth) diffable.
+
+These are the wrappers whose payload is a **base scalar**, so they can be shared by both halves of the
+manifest without either half importing the other. A wrapper over a *domain* type lives next to that
+type — :class:`~seqforge.models.dataset.EvidencedReadLayout` in ``dataset``,
+:class:`~seqforge.models.processing.EvidencedGenome` in ``processing``. That is not a stylistic
+preference: it is what keeps ``dataset`` and ``processing`` from importing each other, and that
+independence is the two-artifact split expressed as an import graph rather than as a comment.
+
+    base  ->  evidenced  ->  dataset
+                         ->  processing        (dataset and processing never meet)
+"""
+
+from __future__ import annotations
+
+from .base import Accession, AssayTerm, ChemistryId, Evidenced, NcbiTaxid
+
+
+class EvidencedStr(Evidenced[str]):
+    """An ``Evidenced`` string field."""
+
+
+class EvidencedBool(Evidenced[bool]):
+    """An ``Evidenced`` boolean field."""
+
+
+class EvidencedTaxid(Evidenced[NcbiTaxid]):
+    """An ``Evidenced`` NCBI taxid."""
+
+
+class EvidencedAssay(Evidenced[AssayTerm]):
+    """An ``Evidenced`` EFO/OBI assay CURIE."""
+
+
+class EvidencedChemistrySet(Evidenced[list[ChemistryId]]):
+    """An ``Evidenced`` chemistry equivalence class (benign twins recorded together, §12)."""
+
+
+class EvidencedAccessionList(Evidenced[list[Accession]]):
+    """An ``Evidenced`` list of accessions."""
+
+
+__all__ = [
+    "EvidencedStr",
+    "EvidencedBool",
+    "EvidencedTaxid",
+    "EvidencedAssay",
+    "EvidencedChemistrySet",
+    "EvidencedAccessionList",
+]