claims-cli 0.6.0__py3-none-any.whl

claims/core/manifest.py

@@ -0,0 +1,349 @@
+"""What a project declares: its artifacts, its runs, and how they were produced.
+
+The `Manifest` model lives here; reading one off disk is `claims.manifest`."""
+
+from __future__ import annotations
+
+import enum
+import pathlib
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, model_validator
+
+from claims.core.artifacts import ArtifactRef, Digest
+from claims.core.claims import Claim
+from claims.core.evidence import Conversion
+from claims.core.outcomes import RegistrationAuthority
+
+SCHEMA_VERSION = "repro/1"
+
+_SHA256_HEX = r"^[a-f0-9]{64}$"
+
+
+# ---------------------------------------------------------------------------------- manifest
+
+
+class Provenance(BaseModel):
+    """Where a manifest's artifacts came from.
+
+    Recorded, never verified. The pin is the artifact's digest: a commit identifies a tree,
+    and a tree does not establish that the file on disk today is the file that was in it.
+    A reader who wants these exact bytes uses the commit to fetch them and the digest to
+    confirm they arrived.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    repository: str = ""
+    """Remote URL, or a local path where there is no remote."""
+
+    commit: str = ""
+    """Full SHA of the revision the artifacts were read from."""
+
+    dirty: bool = False
+    """Whether the working tree had uncommitted changes when the manifest was written. A
+    manifest built from a dirty tree names a commit that does not contain what was read."""
+
+    generated_by: str = ""
+    """The script that wrote this manifest, so the figures can be regenerated."""
+
+
+class RunOutput(BaseModel):
+    """An artifact a run produced, bound by digest rather than by name.
+
+    Naming the artifact alone is not a binding: a later file written to the same path can be
+    presented as the output of an earlier run, which is the manoeuvre the ordering check
+    exists to detect. A run that records no digest is reported `run_output_unlinked`.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    artifact: str
+    digest: Digest | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _accept_a_bare_id(cls, data):
+        """`outputs: [results]` parses, and is reported as unlinked rather than rejected."""
+        return {"artifact": data} if isinstance(data, str) else data
+
+
+class RunRecord(BaseModel):
+    """A computation that produced artifacts, and the plan it was registered under."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str
+    registered_plan: str = ""
+    """The plan this run was registered under. Where it names a declared artifact, that
+    document is pinned, so it cannot be edited after the fact without breaking the pin."""
+
+    registration_authority: RegistrationAuthority = RegistrationAuthority.SELF_RECORDED
+    """Who attests to `registered_at`. Defaults to the weakest, which is what an unqualified
+    timestamp in a file actually is."""
+
+    registered_at: AwareDatetime | None = None
+    started_at: AwareDatetime | None = None
+    """Both must carry an offset. A naive timestamp compared against an aware one is either a
+    crash or a silently wrong ordering, and an ordering that is wrong by a timezone is the
+    failure this check exists to catch."""
+
+    outputs: tuple[RunOutput, ...] = ()
+
+    def output(self, artifact_id: str) -> RunOutput | None:
+        return next((o for o in self.outputs if o.artifact == artifact_id), None)
+
+
+class Regeneration(enum.StrEnum):
+    """What happened when a declared command was run again.
+
+    The verdict is about the numbers the manuscript prints from the output, never about its
+    bytes: a re-run that names a different file for the same value has reproduced every number
+    and matched no digest. Whether the bytes matched is recorded beside the verdict.
+    """
+
+    REPRODUCED = "reproduced"
+    """Re-ran, and every number the manuscript prints from the output still holds."""
+    CHANGED = "changed"
+    """Re-ran, and at least one number the manuscript prints from the output is now different."""
+    UNCHECKED = "unchecked"
+    """Re-ran and wrote the output, but a number could not be read from it."""
+    FAILED = "failed"
+    """The command did not finish, or finished and wrote nothing."""
+    NOT_RERUN = "not_rerun"
+    """Never executed. The reason says why: skipped, or the inputs are not the ones declared."""
+
+
+class RegenerationReason(enum.StrEnum):
+    OUTPUT_MATCHES = "output_matches"
+    """The output has the pinned bytes, after any volatile fields are removed."""
+    CLAIMS_HOLD = "claims_hold"
+    """The bytes differ and every assertion reading the output holds against the new file."""
+    CLAIM_CHANGED = "claim_changed"
+    CLAIM_UNREADABLE = "claim_unreadable"
+    """The bytes differ and an assertion could not be evaluated against the new file."""
+    NO_CLAIM_READS_OUTPUT = "no_claim_reads_output"
+    """The bytes differ and no assertion reads the output, so bytes are all there is to compare."""
+    SKIPPED = "skipped"
+    INPUT_UNPINNED = "input_unpinned"
+    INPUT_CHANGED = "input_changed"
+    INPUT_MISSING = "input_missing"
+    COMMAND_FAILED = "command_failed"
+    """The command exited non-zero. Where the inputs were copied into an empty directory,
+    this also catches a script that needs a file the manifest never declared."""
+    COMMAND_TIMED_OUT = "command_timed_out"
+    OUTPUT_NOT_PRODUCED = "output_not_produced"
+    OUTPUT_UNPINNED = "output_unpinned"
+    """The record names no expected digest for its output."""
+    OUTPUT_NOT_THE_ARTIFACT = "output_not_the_artifact"
+    """The record's expected output is not the artifact the claims were checked against, so
+    reproducing it would say nothing about the manuscript's numbers."""
+    OUTPUT_IS_ALSO_AN_INPUT = "output_is_also_an_input"
+    """The output was copied into the sandbox as one of its own inputs, so a command that does
+    nothing reproduces it."""
+    OUTPUT_OUTSIDE_SANDBOX = "output_outside_sandbox"
+    RUNNER_UNAVAILABLE = "runner_unavailable"
+
+
+class RegenerationRecord(BaseModel):
+    """A command that produces an artifact from declared inputs.
+
+    The honest analogue of the ordering check for a measurement no plan could have
+    registered: not "did this follow its plan" but "does the pinned code, over the pinned
+    inputs, still produce this". Opt-in, because it executes a command.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str
+    command: tuple[str, ...]
+    """argv, never a shell string. A shell string needs quoting rules, brings a shell's
+    expansion with it, and turns a manifest into something that can run anything."""
+
+    inputs: tuple[RunOutput, ...] = ()
+    """Every artifact the command reads. Only these are placed in the working directory, so
+    a command needing an undeclared file fails and says so."""
+
+    output: RunOutput
+    """The artifact the command writes, and the digest it is expected to have."""
+
+    volatile: tuple[str, ...] = ()
+    """JSON Pointers to fields removed before comparing. Literal byte identity is the right
+    test only after timestamps, paths and environment metadata are controlled; naming them
+    keeps the comparison honest instead of loosening it everywhere."""
+
+    timeout_seconds: float = 300.0
+
+    @model_validator(mode="after")
+    def _command_is_not_empty(self):
+        if not self.command:
+            raise ValueError(f"regeneration {self.id!r}: command is empty")
+        return self
+
+
+class Reading(enum.StrEnum):
+    """One assertion, evaluated against the file a re-run wrote."""
+
+    HOLDS = "holds"
+    CHANGED = "changed"
+    """It held against the pinned file and does not hold against the new one."""
+    ALREADY_MISMATCHED = "already_mismatched"
+    """The new file holds what the pinned file holds, and the manuscript prints something else.
+    The re-run changed nothing here; `repro verify` reports the disagreement."""
+    UNREADABLE = "unreadable"
+
+
+class ClaimReading(BaseModel):
+    """What one assertion found in the pinned output and in the re-run's output."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    claim_id: str
+    name: str = ""
+    printed: str = ""
+    """The value as the manuscript prints it."""
+    pinned: str | None = None
+    """The value in the pinned file, as stored."""
+    fresh: str | None = None
+    """The value in the file the re-run wrote, as stored."""
+    difference: str | None = None
+    """`fresh - pinned`, where both are numbers."""
+    conversion: Conversion | None = None
+    """The conversion the assertion declares, or None. The manuscript prints the value under
+    it, so `pinned` and `fresh` are in another unit than `printed` where one is declared."""
+    pinned_converted: str | None = None
+    """`pinned` under `conversion`. None where no conversion is declared, or where the pinned
+    file holds no number at the address."""
+    fresh_converted: str | None = None
+    """`fresh` under `conversion`, which is the value compared with `printed`."""
+    reading: Reading
+    detail: str = ""
+
+
+class InputReading(BaseModel):
+    """One declared input: the digest the record names and the digest found on disk."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    artifact_id: str
+    path: str = ""
+    pinned: str | None = None
+    observed: str | None = None
+
+
+class RegenerationState(BaseModel):
+    """What happened when a regeneration record was run again."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    regeneration_id: str
+    artifact_id: str
+    state: Regeneration
+    reason: RegenerationReason
+    expected: str | None = None
+    actual: str | None = None
+    detail: str = ""
+
+    executed: bool = False
+    """Whether the command was started. False for a record that was skipped or refused."""
+    bytes_identical: bool | None = None
+    """Whether the output had the pinned bytes. None where no output was compared."""
+    claims: tuple[ClaimReading, ...] = ()
+    """Each assertion reading the output, where the bytes differed and the claims were read."""
+    rests_on: tuple[str, ...] = ()
+    """Records producing an input of this one that did not themselves reproduce. This record
+    ran over their pinned outputs, so its result is conditional on them."""
+
+    command: tuple[str, ...] = ()
+    exit_code: int | None = None
+    duration_seconds: float | None = None
+    stdout_digest: str | None = None
+    stderr_digest: str | None = None
+    inputs: tuple[InputReading, ...] = ()
+    undeclared_outputs: tuple[str, ...] = ()
+    """Files the command wrote that the record does not declare, relative to its directory."""
+
+
+class SetAside(BaseModel):
+    """A passage whose numbers the author declares are not claims, and why.
+
+    `repro numbers` counts every number a text prints. A number in a passage listed here is
+    counted as set aside with a reason and printed with that reason, never dropped.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    artifact: str
+    """Id of the text artifact the passage is in."""
+
+    text: str = Field(min_length=1)
+    """The passage, matched as a quotation is. Every number inside each place it occurs is
+    set aside, unless an assertion binds it."""
+
+    reason: str = Field(min_length=1)
+    """Why no assertion is offered for these numbers. Required: an entry without one would be
+    a way to shrink the count of unbound numbers without saying anything."""
+
+
+class Manifest(BaseModel):
+    """One project: its artifacts and its claims."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: str = SCHEMA_VERSION
+    project: str = ""
+    provenance: Provenance | None = None
+    artifacts: tuple[ArtifactRef, ...] = ()
+    claims: tuple[Claim, ...] = ()
+    runs: tuple[RunRecord, ...] = ()
+    regenerations: tuple[RegenerationRecord, ...] = ()
+    set_aside: tuple[SetAside, ...] = ()
+
+    path: pathlib.Path | None = Field(default=None, exclude=True)
+
+    @model_validator(mode="after")
+    def _ids_are_unique(self):
+        """Two artifacts with one id is not a manifest with a duplicate; it is a manifest that
+        says two different things about the same name.
+
+        The engine keys its state by id, so a duplicate silently kept the last declaration and
+        dropped the rest -- including, in the case that matters, a broken pin, which then
+        disappeared from the report entirely and left `strict` passing with no violations.
+        Claims are checked the same way for the same reason, and so are regenerations: a
+        re-run is recorded under its id, and two records sharing one cannot be told apart in
+        the record of re-runs.
+        """
+        for label, items in (
+            ("artifact", self.artifacts),
+            ("claim", self.claims),
+            ("regeneration", self.regenerations),
+        ):
+            seen: set[str] = set()
+            for item in items:
+                if item.id in seen:
+                    raise ValueError(
+                        f"duplicate {label} id {item.id!r}: one id must name one thing"
+                    )
+                seen.add(item.id)
+        return self
+
+    @model_validator(mode="after")
+    def _one_regeneration_writes_an_artifact(self):
+        """Which command produced a file has one answer. With two records naming one output,
+        the last declared was taken as the producer and the other was never consulted."""
+        producers: dict[str, str] = {}
+        for record in self.regenerations:
+            other = producers.setdefault(record.output.artifact, record.id)
+            if other != record.id:
+                raise ValueError(
+                    f"regenerations {other!r} and {record.id!r} both write artifact "
+                    f"{record.output.artifact!r}: one artifact has one producer"
+                )
+        return self
+
+    def artifact(self, artifact_id: str) -> ArtifactRef | None:
+        return next((a for a in self.artifacts if a.id == artifact_id), None)
+
+    def resolve(self, artifact: ArtifactRef) -> pathlib.Path:
+        if artifact.path.is_absolute() or self.path is None:
+            return artifact.path
+        return (self.path.parent / artifact.path).resolve()

claims/core/numbers.py

@@ -0,0 +1,146 @@
+"""What an inventory of the numbers a text prints found."""
+
+from __future__ import annotations
+
+import collections
+import enum
+
+from pydantic import BaseModel, ConfigDict
+
+from claims.core.evidence import NumberForm
+
+SCHEMA_VERSION = "repro/1"
+
+
+class Standing(enum.StrEnum):
+    """Where one printed number stands against the manifest. Each number has exactly one."""
+
+    BOUND = "bound"
+    """A declared assertion accounts for this occurrence: it lies in the passage of a `quote`
+    whose claim reports its value from a file, or it is the value a prose address selects."""
+    SET_ASIDE_WITH_A_REASON = "set_aside_with_a_reason"
+    """It lies in a passage the manifest lists under `set_aside`, which carries the reason."""
+    SET_ASIDE_BY_RULE = "set_aside_by_rule"
+    """A named rule reads it as something other than a quantity: a year, a table's number."""
+    UNBOUND = "unbound"
+    """Printed, and nothing in the manifest accounts for it."""
+
+
+class NumberRule(enum.StrEnum):
+    """Why a run of digits is set aside without the author saying so. Applied in this order,
+    and the first that holds is the one named."""
+
+    LINK = "link"
+    """Inside a URL."""
+    DATE = "date"
+    """One of the three parts of a date written `2026-10-13`."""
+    DOCUMENT = "document_identifier"
+    """The number a document is known by: what follows `rfc`, `iso`, `iec`, `ieee`, `ansi`,
+    `ecma`, `fips`, `pep`, `arxiv`, `doi`, `isbn`, `issn`, `pmid` or `pmcid`, as in `rfc 6901`
+    and `arxiv 2609.22111`, and the digits of a DOI."""
+    NAME = "name"
+    """Part of a name: a letter stands immediately before the digits, `v15zw` and `sha256sum`,
+    or a hyphen or underscore joins them to a part that holds a letter, `gpt-4` and `9750` in
+    `i7-9750h`, or the digits open a run of letters and digits that holds more digits later,
+    as a hexadecimal digest does. An em or en dash is punctuation and joins nothing."""
+    VERSION_OR_SECTION = "version_or_section"
+    """Digits joined by two or more full stops, `0.5.5` and `3.2.1`."""
+    CITATION = "citation"
+    """Whole numbers from 1 up, alone in square brackets: `[12]`, `[3, 7]`, `[4-6]`."""
+    LABEL = "label"
+    """The number of a section, figure, table, equation, appendix, chapter, page, algorithm,
+    listing, theorem, lemma, proposition, corollary, definition, footnote, step or line: it
+    follows that word, and a range written `2-4` after the word is two labels."""
+    LIST_MARKER = "list_marker"
+    """A whole number of one or two digits alone in parentheses, `(1)`: an item of a list or
+    the number of an equation."""
+    ORDINAL = "ordinal"
+    """Digits with `st`, `nd`, `rd` or `th` attached: `3rd`, `95th`."""
+    YEAR = "year"
+    """Four digits from 1800 to 2099 with no sign, separator, decimal point or percent sign."""
+    THE_WORD_ONE = "the_word_one"
+    """The word `one`, which is a pronoun more often than a count. Every other cardinal
+    written as one word, `eighteen` and `thirty-five`, is counted as a number."""
+
+
+class PrintedNumber(BaseModel):
+    """One occurrence of a number in a text."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    text: str
+    """As printed, after the normalization a quotation is matched under: `2,364`, `-0.42`,
+    `24.11%`, `eighteen`."""
+    value: str | None = None
+    """The decimal it is read as, without grouping commas or a percent sign. None for digits
+    no value is read from: a name, a link, a document's identifier, a version."""
+    form: NumberForm = NumberForm.DECIMAL
+    """Whether it is printed in digits or as a word."""
+    offset: int
+    """Where it starts in the normalized text."""
+    line: int | None = None
+    """The line of the extracted text it is on, from 1. None where the lines could not be
+    matched to the normalized text."""
+    context: str = ""
+    """The words on either side."""
+    standing: Standing
+    rule: NumberRule | None = None
+    claims: tuple[str, ...] = ()
+    """The claims whose assertions bind it."""
+    reason: str = ""
+    """The author's reason, where the manifest sets it aside."""
+    reported_elsewhere: bool = False
+    """Of an unbound number only: some assertion in the manifest reports this value, and
+    none accounts for this occurrence. Marked where the value has two digits or more, or a
+    decimal point."""
+    reported_elsewhere_one_digit: bool = False
+    """The same, for a value of one digit and no decimal point. Most manifests report some
+    `4`, so the match says little: it is counted and not marked."""
+
+
+class TextInventory(BaseModel):
+    """Every number one text artifact prints, in the order printed."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    artifact: str
+    path: str = ""
+    numbers: tuple[PrintedNumber, ...] = ()
+
+
+class SetAsideCount(BaseModel):
+    """One `set_aside` entry of the manifest, and how many numbers it accounts for."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    artifact: str
+    text: str
+    reason: str
+    numbers: int
+    """0 where the passage is not in the text, or holds no number that is not bound."""
+
+
+class NumbersReport(BaseModel):
+    """What `repro numbers` found. Frozen, and carries no verdict."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: str = SCHEMA_VERSION
+    project: str = ""
+    manifest_digest: str = ""
+    texts: tuple[TextInventory, ...] = ()
+    set_aside: tuple[SetAsideCount, ...] = ()
+
+    @property
+    def numbers(self) -> tuple[PrintedNumber, ...]:
+        return tuple(number for text in self.texts for number in text.numbers)
+
+    @property
+    def counts(self) -> collections.Counter[Standing]:
+        return collections.Counter(number.standing for number in self.numbers)
+
+    @property
+    def rules(self) -> collections.Counter[NumberRule]:
+        """How many numbers each rule set aside, in the order the rules are applied."""
+        found = collections.Counter(number.rule for number in self.numbers if number.rule)
+        return collections.Counter({rule: found[rule] for rule in NumberRule if found[rule]})