claims-cli 0.6.0__py3-none-any.whl

claims/adapters/columnar.py

@@ -0,0 +1,188 @@
+"""Binary formats that hold one table: Parquet, Feather, Arrow, Stata, SPSS, and R's `.rds`.
+
+Each is read into the header and rows a delimited file gives, with every cell rendered by
+`claims.adapters.cells`, and resolved by `claims.adapters.rows`. A table locator therefore
+addresses `results.parquet` exactly as it addresses `results.csv`, and the same table in either
+format refuses and resolves the same manifests.
+
+Every reader is an optional extra, and a missing one raises `BackendUnavailableError` naming
+it, which the engine reports as `unchecked`:
+
+    .parquet .feather .arrow   pyarrow      reproducible-science[parquet]
+    .dta .sav .zsav            pyreadstat   reproducible-science[stata-spss]
+    .rds                       rdata        reproducible-science[rds]
+
+**No reader here executes the file.** A pickle is a program, and an `.rds` read by R can be
+one: R's deserializer evaluated a promise embedded in the stream when the restored object was
+first used (CVE-2024-27322). `rdata` is a parser of R's serialization format written in Python.
+It builds the objects the bytes describe and evaluates nothing, and no R process is started.
+`pyreadr` would also avoid R, and is not used because it is AGPL.
+"""
+
+from __future__ import annotations
+
+import lzma
+import pathlib
+import zlib
+
+from claims.adapters.cells import Cell, Container, render, shortest_single
+from claims.exceptions import ArtifactUnreadableError, BackendUnavailableError
+from claims.toolchain import DISTRIBUTION
+
+try:  # optional: `pip install "reproducible-science[parquet]"`
+    import pyarrow
+    import pyarrow.compute
+    import pyarrow.feather
+    import pyarrow.parquet
+except ImportError:  # pragma: no cover - exercised by the extras matrix, not the suite
+    pyarrow = None
+
+try:  # optional: `pip install "reproducible-science[stata-spss]"`
+    import pyreadstat
+except ImportError:  # pragma: no cover
+    pyreadstat = None
+
+try:  # optional: `pip install "reproducible-science[rds]"`
+    import rdata
+except ImportError:  # pragma: no cover
+    rdata = None
+
+_ARROW_SUFFIXES = {".parquet", ".feather", ".arrow"}
+_READSTAT_SUFFIXES = {".dta", ".sav", ".zsav"}
+COLUMNAR_SUFFIXES = _ARROW_SUFFIXES | _READSTAT_SUFFIXES | {".rds"}
+
+Frame = tuple[list[str], list[dict[str, Cell]]]
+
+
+def read_columnar(path: pathlib.Path, wanted: set[str]) -> Frame:
+    """The file's header, and its rows restricted to the `wanted` columns it has.
+
+    Only the columns a locator names are read. A results file can hold thousands of columns,
+    and the header alone settles whether the locator names columns the file has.
+    """
+    suffix = path.suffix.lower()
+    if suffix in _ARROW_SUFFIXES:
+        return _arrow(path, wanted)
+    if suffix in _READSTAT_SUFFIXES:
+        return _readstat(path, wanted)
+    return _rds(path, wanted)
+
+
+def _rows(header: list[str], columns: dict[str, list[Cell]], n: int) -> Frame:
+    return header, [{name: cells[i] for name, cells in columns.items()} for i in range(n)]
+
+
+def _addressable(header: list[str], wanted: set[str]) -> list[str]:
+    """The wanted columns that occur once. A repeated name is refused before any row is read."""
+    return [name for name in header if name in wanted and header.count(name) == 1]
+
+
+# ------------------------------------------------------------------------------------ arrow
+
+
+_NO_PYARROW = f'pyarrow is not installed -- pip install "{DISTRIBUTION}[parquet]"'
+
+
+def _arrow(path: pathlib.Path, wanted: set[str]) -> Frame:
+    if pyarrow is None:
+        raise BackendUnavailableError("table", _NO_PYARROW)
+    try:
+        if path.suffix.lower() == ".parquet":
+            header = list(pyarrow.parquet.read_schema(path).names)
+            table = pyarrow.parquet.read_table(path, columns=_addressable(header, wanted))
+        else:
+            table = pyarrow.feather.read_table(path)
+            header = list(table.column_names)
+    except (pyarrow.ArrowException, OSError) as e:
+        raise ArtifactUnreadableError(path, f"not a readable {path.suffix} file: {e}") from e
+    columns = {name: _arrow_cells(table.column(name)) for name in _addressable(header, wanted)}
+    return _rows(header, columns, table.num_rows)
+
+
+def _arrow_cells(column) -> list[Cell]:
+    """A column as text, by Arrow's own cast.
+
+    Arrow renders a float as the shortest decimal that round-trips at the column's own width,
+    so a `float32` 0.1 is `0.1` rather than the 0.10000000149011612 a conversion to a Python
+    float produces. A nested column has no text form, and each of its cells is a container.
+    """
+    if pyarrow is None:  # pragma: no cover - `_arrow` has already raised
+        raise BackendUnavailableError("table", _NO_PYARROW)
+    kind = column.type
+    if pyarrow.types.is_nested(kind) or pyarrow.types.is_union(kind):
+        return [
+            None if v is None else Container(holds=f"an Arrow {kind}") for v in column.to_pylist()
+        ]
+    try:
+        text = pyarrow.compute.cast(column, pyarrow.string()).to_pylist()
+    except pyarrow.ArrowException:
+        # Binary that is not UTF-8, an extension type: there is no text to compare.
+        return [
+            None if v is None else Container(holds=f"an Arrow {kind}") for v in column.to_pylist()
+        ]
+    return [render(v) for v in text]
+
+
+# --------------------------------------------------------------------------------- readstat
+
+
+def _readstat(path: pathlib.Path, wanted: set[str]) -> Frame:
+    if pyreadstat is None:
+        raise BackendUnavailableError(
+            "table",
+            f'pyreadstat is not installed -- pip install "{DISTRIBUTION}[stata-spss]"',
+        )
+    read = pyreadstat.read_dta if path.suffix.lower() == ".dta" else pyreadstat.read_sav
+    try:
+        _, meta = read(str(path), metadataonly=True, output_format="dict")
+        header = list(meta.column_names)
+        usecols = _addressable(header, wanted)
+        data, meta = read(str(path), usecols=usecols, output_format="dict")
+    except (pyreadstat.ReadstatError, pyreadstat.PyreadstatError, OSError) as e:
+        raise ArtifactUnreadableError(path, f"not a readable {path.suffix} file: {e}") from e
+    # Value labels are not applied: a labelled column is matched and read by its stored code,
+    # which is what the file holds. Applying them would make a predicate depend on a label set
+    # the analyst can change without touching a single value.
+    widths = meta.readstat_variable_types
+    columns = {
+        name: [
+            shortest_single(v)
+            if widths.get(name) == "float" and isinstance(v, float)
+            else render(v)
+            for v in data[name]
+        ]
+        for name in usecols
+    }
+    return _rows(header, columns, meta.number_rows or 0)
+
+
+# -------------------------------------------------------------------------------------- rds
+
+
+def _rds(path: pathlib.Path, wanted: set[str]) -> Frame:
+    if rdata is None:
+        raise BackendUnavailableError(
+            "table", f'rdata is not installed -- pip install "{DISTRIBUTION}[rds]"'
+        )
+    try:
+        frame = rdata.read_rds(path)
+    except (ValueError, NotImplementedError, EOFError, OSError, zlib.error, lzma.LZMAError) as e:
+        raise ArtifactUnreadableError(path, f"not a readable .rds file: {e}") from e
+    if type(frame).__name__ != "DataFrame" or not hasattr(frame, "columns"):
+        # A model fit, a vector, a list: an .rds holds any one R object. Only a data frame is a
+        # table, and a value inside anything else has no address this locator can give.
+        raise ArtifactUnreadableError(
+            path, f"holds an R object read as {type(frame).__name__}, not a data frame"
+        )
+    header = [str(c) for c in frame.columns]
+    columns = {}
+    for name in _addressable(header, wanted):
+        series = frame[name]
+        # R's `NA` reaches pandas as NaN or `pd.NA` depending on the column type, and
+        # `isna` is the one test that recognizes both.
+        missing = series.isna().tolist()
+        columns[name] = [
+            None if absent else render(v)
+            for v, absent in zip(series.tolist(), missing, strict=True)
+        ]
+    return _rows(header, columns, len(frame))

claims/adapters/prose.py

@@ -0,0 +1,261 @@
+"""The value between two literal anchors in the text of a document.
+
+Every other adapter translates a locator into the addressing its format already has. Prose has
+none: a sentence is not a tree, a table, or an indexed array. What a document does have is the
+text on either side of a number, and that is the address this adapter resolves -- the author
+writes the literal that precedes the value and the literal that follows it, and the adapter
+returns what sits between.
+
+Nothing here searches for a number. A pattern that found "the first integer in the paragraph"
+would locate a number wherever one appeared and call that verification, which is the failure
+`claims.adapters.base` exists to prevent.
+
+The text is the text a quotation resolves against: `citations.verify.extract` produces it and
+`citations.verify.passage_fold` normalizes it, so an anchor and a `quote` assertion over the same
+document cannot disagree about what the document says.
+"""
+
+from __future__ import annotations
+
+import decimal
+import pathlib
+import re
+from collections.abc import Iterator
+
+from claims.adapters.base import Found, Resolution, _no, _ok
+from claims.adapters.reads import once
+from claims.exceptions import ArtifactUnreadableError, BackendUnavailableError
+from claims.models import NumberForm, ProseLocator
+
+_UNITS = (
+    "zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen "
+    "fifteen sixteen seventeen eighteen nineteen"
+).split()
+
+_TENS = "twenty thirty forty fifty sixty seventy eighty ninety".split()
+
+
+def _cardinals() -> dict[str, int]:
+    """English cardinals below one hundred, as one word each.
+
+    The bound is not arbitrary: the value a prose locator selects is a run of non-whitespace
+    characters, and every cardinal above ninety-nine is written as several words. Extending
+    the table would not make `one hundred and forty-five` addressable.
+
+    The table names a conversion the manifest has to ask for. It is also read under
+    `form: decimal`, where a hit means the value is refused with `number_as_word` rather than
+    reported as a missing number -- an author who spelled the count out should be told that,
+    not sent looking for a broken anchor.
+    """
+    table = {word: value for value, word in enumerate(_UNITS)}
+    for index, tens in enumerate(_TENS):
+        base = 20 + index * 10
+        table[tens] = base
+        for unit in range(1, 10):
+            table[f"{tens}-{_UNITS[unit]}"] = base + unit
+    return table
+
+
+CARDINALS = _cardinals()
+
+#: A number as it is printed, for deciding where an anchor may not fall. The digits, grouping
+#: underscores, decimal point and exponent are the unsigned part of what `decimal.Decimal`
+#: parses, which is what reads the value in `_is_decimal` here and in `claims.verify`. The comma
+#: is not: `Decimal("1,234")` is refused. It is here because a document prints `1,234`, and an
+#: anchor that cut it at the comma would have `1` read as the value.
+#:
+#: A match counts only where no letter stands immediately before it. Digits attached to a
+#: letter are part of a name -- the version `v0.5`, the label `H10` -- and an anchor may fall
+#: among them. Punctuation does not make a name: `x=0.318`, `(0.318` and `p<0.05` hold numbers,
+#: and so does a number with letters after it, `5kg`.
+#:
+#: A sign immediately before the digits belongs to the number where it opens the run or follows
+#: a character that is neither a digit nor a letter: `x=-0.42`, `(-0.42)`, `| -0.42|`. After a
+#: digit or a letter it is a range, a subtraction or a hyphen, `10-12` and `pre-2020`, and the
+#: digits after it are a number of their own. `passage_fold` has already written U+2212 and
+#: the dashes as `-` by the time this is read; the character is listed for a caller that has not.
+_SIGNS = "+-\u2212"
+_NUMBER = re.compile(r"\d+(?:_\d+)*(?:[.,]\d+(?:_\d+)*)*(?:[eE][+-]?\d+)?")
+
+
+def numerals(text: str, lo: int = 0, hi: int | None = None) -> Iterator[tuple[int, int, bool]]:
+    """Each run of digits in `text[lo:hi]` that is printed as a number: where it starts, its
+    sign included, where it ends, and whether a letter stands immediately before it.
+
+    The last is the rule above: with a letter before them the digits are part of a name, and
+    no sign is read for a name."""
+    for number in _NUMBER.finditer(text, lo, len(text) if hi is None else hi):
+        first = number.start()
+        if first > 0 and text[first - 1].isalpha():
+            yield first, number.end(), True
+            continue
+        if first > 0 and text[first - 1] in _SIGNS:
+            sign = first - 1
+            if sign == 0 or not text[sign - 1].isalnum():
+                first = sign
+        yield first, number.end(), False
+
+
+def _split(text: str, at: int) -> str:
+    """The number `at` falls strictly inside, or the empty string where it splits none."""
+    lo = at
+    while lo > 0 and not text[lo - 1].isspace():
+        lo -= 1
+    hi = at
+    while hi < len(text) and not text[hi].isspace():
+        hi += 1
+    for first, end, named in numerals(text, lo, hi):
+        if not named and first < at < end:
+            return text[first:end]
+    return ""
+
+
+def _is_decimal(text: str) -> bool:
+    try:
+        decimal.Decimal(text)
+    except (decimal.InvalidOperation, ValueError):
+        return False
+    return True
+
+
+def _resolve_prose(locator: ProseLocator, path: pathlib.Path) -> Found:
+    # Imported here for the reason `QuoteBackend` imports it here: an installation without a
+    # working extractor must report a check that did not run, not fail to import the package.
+    try:
+        from citations.exceptions import SourceUnreadableError
+        from citations.verify import extract_uncached, passage_fold
+    except ImportError as e:  # pragma: no cover - citations is a declared dependency
+        raise BackendUnavailableError("prose", f"citations is not installed: {e}") from e
+
+    # `extract` is cached on the path, so a second verification in one process reads the text
+    # the first one extracted, whatever the file now holds. `extract_uncached` is the named
+    # read; this reached it through `extract.__wrapped__` until that attribute stopped existing
+    # and the `getattr` fallback quietly returned the cached function instead. The engine hashes every artifact
+    # immediately before this runs, so a stale read would produce a decision whose recorded
+    # artifact digest does not describe the text it was computed from. `fold` is cached on the
+    # string it is given, which is content, and stays as it is. `once` keeps the read for the
+    # verification in progress and no longer, so the next verification reads the file again.
+    try:
+        text = once(("prose", path), lambda: passage_fold(extract_uncached(path)))
+    except SourceUnreadableError as e:
+        raise ArtifactUnreadableError(path, e.detail) from e
+    if not text:
+        raise ArtifactUnreadableError(path, "no text extracted")
+
+    # `fold` trims and collapses whitespace, which is what an anchor wants: the boundary
+    # spaces are supplied by `_spans`, and an anchor written across a line break in the
+    # manifest matches a document that wrapped it somewhere else.
+    before, after = passage_fold(locator.before), passage_fold(locator.after)
+    if not before:
+        return _no(
+            Resolution.SELECTOR_INVALID,
+            "`before` is empty after normalization, so it anchors nothing",
+        )
+
+    hits, split = _spans(text, before, after)
+    address = (
+        f'"{locator.before}" ... "{locator.after}"' if locator.after else f'"{locator.before}"'
+    )
+    if not hits:
+        refused = (
+            f"; an anchor never splits a number, and these would split {', '.join(split)}"
+            if split
+            else ""
+        )
+        return _no(
+            Resolution.ABSENT,
+            f"no value sits between {address} in {path.name}; anchors are literal text, "
+            f"matched after the same normalization a quotation is matched under{refused}",
+        )
+    values = sorted(set(hits))
+    if len(values) > 1:
+        # Repetition is normal in a document and is not ambiguity: a count stated in an
+        # abstract and again in a section is one value. Two *different* values between the
+        # same anchors is a document contradicting itself, which is a finding rather than a
+        # thing to resolve by taking the first.
+        return _no(
+            Resolution.PASSAGE_AMBIGUOUS,
+            f"{address} selects {len(values)} different values in {path.name}: {', '.join(values)}",
+        )
+
+    value = values[0]
+    seen = f"{len(hits)} occurrence(s)" if len(hits) > 1 else ""
+    trace = (address, seen) if seen else (address,)
+
+    if locator.form is NumberForm.CARDINAL_WORD:
+        if (number := CARDINALS.get(value)) is not None:
+            return _ok(str(number), "cardinal_word", *trace, f'the word "{value}"')
+        # A numeral where a word was declared still parses, and refusing it would break a
+        # check because someone corrected the prose. Anything else falls through to the
+        # backend, which reports it as not numeric.
+        return _ok(value, "text", *trace)
+
+    if not _is_decimal(value) and value in CARDINALS:
+        return _no(
+            Resolution.NUMBER_AS_WORD,
+            f'{address} holds "{value}" in {path.name}. Reading a word as a number is a '
+            f"semantic decision the engine does not make on its own; declare "
+            f"`form: cardinal_word` on the locator to ask for it",
+        )
+    return _ok(value, "decimal" if _is_decimal(value) else "text", *trace)
+
+
+def _spans(text: str, before: str, after: str) -> tuple[list[str], list[str]]:
+    """The value after each occurrence of `before`, and the numbers an anchor would have split."""
+    found, split = located(text, before, after)
+    return [text[start:end] for start, end in found], split
+
+
+def located(text: str, before: str, after: str) -> tuple[list[tuple[int, int]], list[str]]:
+    """Where the value after each occurrence of `before` starts and ends, and the numbers an
+    anchor would have split.
+
+    The value is a run of non-whitespace characters. With no `after` it is the whole run up to
+    the next whitespace. With one, the whole run is taken where `after` begins past it, and
+    otherwise the run is cut at the first place inside it where `after` begins: a cell printed
+    against its divider, `0.318|`, or a number closing a sentence, `3.14.`, is delimited by
+    the anchor that touches it and by nothing the engine guessed.
+
+    Neither anchor may fall inside a number. `after: "8"` does not read `0.318` as `0.31`, the
+    first full stop in `3.14.` is passed over for the second, and `before: "0.3"` does not
+    read `18`. An occurrence refused on those grounds yields no value, and the number it
+    would have split is returned so the report can say why. Digits attached to a preceding
+    letter are a name, so `before: "v0."` reads `5` from `v0.5`. A sign is part of its number
+    unless a digit or a letter precedes it, so `before: "x=-"` reads nothing from `x=-0.42`
+    and `before: "10-"` reads `12` from `10-12`.
+
+    Whitespace at an anchor boundary is ignored, on the same grounds `fold` collapses it
+    everywhere else: `before: "holds"` and `before: "holds "` address the same value, and a
+    manifest should not turn on which one the author typed.
+    """
+    found: list[tuple[int, int]] = []
+    split: list[str] = []
+    n, start = len(text), 0
+    while (at := text.find(before, start)) != -1:
+        start = at + 1
+        cursor = at + len(before)
+        if number := _split(text, cursor):
+            split.append(number)
+            continue
+        while cursor < n and text[cursor].isspace():
+            cursor += 1
+        end = cursor
+        while end < n and not text[end].isspace():
+            end += 1
+        if end == cursor:
+            continue
+        tail = end
+        while tail < n and text[tail].isspace():
+            tail += 1
+        if not after or text.startswith(after, tail):
+            found.append((cursor, end))
+            continue
+        for stop in range(cursor + 1, end):
+            if not text.startswith(after, stop):
+                continue
+            if number := _split(text, stop):
+                split.append(number)
+                continue
+            found.append((cursor, stop))
+            break
+    return found, list(dict.fromkeys(split))

claims/adapters/reads.py

@@ -0,0 +1,47 @@
+"""Reading each artifact once in a verification.
+
+An adapter resolves one locator against one file, and a manifest of a thousand claims over one
+table asked for that table to be read and parsed a thousand times. Within `reading_once()` a
+load is kept under its key and returned to every later locator that asks for it.
+
+The scope is one verification and nothing longer. The engine hashes every artifact at the start
+of a run, and a decision records that digest as describing what was read; a file read once in
+the run is read as close to that hash as it can be. Outside the scope nothing is kept, so a
+second verification in the same process reads the file again, whatever the first one saw. A
+cache keyed on the path alone and living as long as the process returned the first run's text
+to the second.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable, Hashable, Iterator
+from contextvars import ContextVar
+from typing import TypeVar, cast
+
+T = TypeVar("T")
+
+_HELD: ContextVar[dict[Hashable, object] | None] = ContextVar("repro_reads", default=None)
+
+
+@contextlib.contextmanager
+def reading_once() -> Iterator[None]:
+    """Keep each load made inside the block until the block ends."""
+    token = _HELD.set({})
+    try:
+        yield
+    finally:
+        _HELD.reset(token)
+
+
+def once(key: Hashable, load: Callable[[], T]) -> T:
+    """`load()`, or what it returned earlier in this run under the same key.
+
+    A load that raises is not kept: every locator over an unreadable file reports it.
+    """
+    held = _HELD.get()
+    if held is None:
+        return load()
+    if key not in held:
+        held[key] = load()
+    return cast(T, held[key])

claims/adapters/rows.py

@@ -0,0 +1,116 @@
+"""Selecting one cell of a table, whatever format the table was read from.
+
+Every table adapter reduces its file to a header and a list of rows, each row a mapping from
+column name to `cells.Cell`, and resolves a locator here. One implementation means a CSV, a
+workbook sheet and a Parquet file holding the same table refuse the same manifests for the same
+reasons, which three copies of this logic would drift away from.
+"""
+
+from __future__ import annotations
+
+from claims.adapters.base import Found, Resolution, _no, _ok
+from claims.adapters.cells import Cell, Container
+
+
+def _header_faults(header: list[str], column: str, where: dict, name: str) -> Found | None:
+    """What is wrong with a header before any row is read, or None.
+
+    Shared by every table, delimited or typed, so a workbook and a CSV holding the same table
+    refuse the same manifests with the same reasons.
+    """
+    repeated = sorted({c for c in header if header.count(c) > 1})
+    if repeated:
+        # `csv.DictReader` keeps the last field of a repeated header, so one of the columns is
+        # unreachable and a predicate naming it reports a present row as absent. Neither is a
+        # fact about the data.
+        return _no(
+            Resolution.SELECTOR_INVALID,
+            f"{name} repeats the column name {', '.join(repr(c) for c in repeated)}; "
+            f"a repeated header makes one of them unaddressable",
+        )
+    if column not in header:
+        return _no(
+            Resolution.COLUMN_ABSENT,
+            f"{name} has no column {column!r}; columns are {', '.join(header[:8])}",
+        )
+    unknown = [k for k in where if k not in header]
+    if unknown:
+        # Left to the row scan this matches nothing and reads as "no such row", blaming the
+        # table for a manifest that named a column the table never had.
+        return _no(
+            Resolution.SELECTOR_INVALID,
+            f"selector names {', '.join(repr(k) for k in unknown)}, which "
+            f"{name} has no column for; columns are {', '.join(header[:8])}",
+        )
+    return None
+
+
+def _cell_found(cell: Cell, column: str, address: str) -> Found:
+    """A selected cell as a resolution. A typed table distinguishes a missing value from text.
+
+    `address` is how the row was picked, `where model='vit'` or `at row 3`.
+    """
+    if cell is None:
+        # The typed readers' null: a Parquet null, an R `NA`, an empty workbook cell, a formula
+        # whose result was never computed. Like a NULL in SQLite it asserts nothing, so it is
+        # absent rather than the empty string a comparison would call non-numeric.
+        return _no(Resolution.ABSENT, f"{column} holds no value {address}")
+    if isinstance(cell, Container):
+        return _no(Resolution.NOT_SCALAR, f"{column} holds {cell.holds} {address}")
+    return _ok(cell, "str", f"{column} {address}")
+
+
+def index_rows(rows: list[dict[str, Cell]], columns: tuple[str, ...]) -> dict[tuple, list[int]]:
+    """Row numbers by the cells each row holds in `columns`, for a table of text cells.
+
+    One pass over the table answers every locator that selects on the same columns, where a
+    scan per locator read every row once for each of them.
+    """
+    index: dict[tuple, list[int]] = {}
+    for at, row in enumerate(rows):
+        index.setdefault(tuple(row.get(column) for column in columns), []).append(at)
+    return index
+
+
+def resolve_rows(
+    header: list[str],
+    rows: list[dict[str, Cell]],
+    column: str,
+    where: dict,
+    name: str,
+    index: dict[tuple, list[int]] | None = None,
+) -> Found:
+    """The one row whose key cells equal `where`, and its cell in `column`.
+
+    `where` holds text already, in the convention of the table it is matched against:
+    `predicate_text` for delimited text, `cells.render` for a typed table. `index` is
+    `index_rows` over the sorted names of `where`, and selects the rows a scan would.
+    """
+    if failure := _header_faults(header, column, where, name):
+        return failure
+    if index is None:
+        matched = [
+            i for i, row in enumerate(rows) if all(row.get(k) == v for k, v in where.items())
+        ]
+    else:
+        matched = index.get(tuple(where[k] for k in sorted(where)), [])
+    described = ", ".join(f"{k}={v!r}" for k, v in where.items())
+    if not matched:
+        return _no(Resolution.ABSENT, f"no row in {name} where {described}")
+    if len(matched) > 1:
+        return _no(Resolution.AMBIGUOUS, f"{len(matched)} rows in {name} where {described}")
+    return _cell_found(rows[matched[0]].get(column), column, f"where {described}")
+
+
+def resolve_row_at(
+    header: list[str], rows: list[dict[str, Cell]], column: str, row: int, name: str
+) -> Found:
+    """The cell in `column` at data row `row`, counting from zero below the header."""
+    if failure := _header_faults(header, column, {}, name):
+        return failure
+    if row >= len(rows):
+        return _no(
+            Resolution.ABSENT,
+            f"{name} has {len(rows)} data rows; row {row} is past the end",
+        )
+    return _cell_found(rows[row].get(column), column, f"at row {row}")