claims-cli 0.6.0__py3-none-any.whl

claims/core/outcomes.py

@@ -0,0 +1,410 @@
+"""The verdict vocabulary: three stages, one derived outcome, and why it obtained.
+
+Execution, extraction and comparison are reported separately. Collapsing them is how a
+missing extractor becomes a quotation that failed to check out."""
+
+from __future__ import annotations
+
+import enum
+
+from pydantic import BaseModel, ConfigDict
+
+from claims.core.evidence import Conversion, Statistic
+
+SCHEMA_VERSION = "repro/1"
+
+_SHA256_HEX = r"^[a-f0-9]{64}$"
+
+
+# ---------------------------------------------------------------------------------- outcomes
+
+
+class ExecutionStatus(enum.StrEnum):
+    COMPLETED = "completed"
+    UNAVAILABLE = "unavailable"
+    """The backend could not run: a missing binary, an unreadable file, an absent registry."""
+    FAILED = "failed"
+    """The backend raised something unexpected. A defect, never a scientific outcome."""
+
+
+class ExtractionStatus(enum.StrEnum):
+    EXTRACTED = "extracted"
+    ABSENT = "absent"
+    """The artifact was read and holds no such value. Silence, which is not contradiction."""
+    INVALID = "invalid"
+    """A value was located and is not of the type the assertion requires."""
+    NOT_ATTEMPTED = "not_attempted"
+
+
+class ComparisonStatus(enum.StrEnum):
+    MATCH = "match"
+    MISMATCH = "mismatch"
+    NOT_APPLICABLE = "not_applicable"
+
+
+class Outcome(enum.StrEnum):
+    """The flattened view, for display and for tools that want one field.
+
+    Derived from the three stages, never set directly, so the flattening cannot drift from
+    what the stages say.
+    """
+
+    VERIFIED = "verified"
+    MISMATCH = "mismatch"
+    NOT_FOUND = "not_found"
+    UNCHECKED = "unchecked"
+    ERROR = "error"
+    NOT_OFFERED = "not_offered"
+
+
+class Ordering(enum.StrEnum):
+    """Whether a confirmatory claim's evidence was produced after the plan it names.
+
+    The outcome is separate from the reason, on the same principle the evidence stages
+    follow: a check that could not run is not a check that failed. `unchecked` carries an
+    `OrderingReason` saying which of nine conditions stopped it, because collapsing a
+    missing run record, an unpinned plan, and an unlinked output into one word loses the
+    only information that says what to fix.
+    """
+
+    ORDERED = "ordered"
+    """Every run producing this claim's evidence started after its plan was registered."""
+    VIOLATED = "violated"
+    """A run started before the plan it names was registered."""
+    UNCHECKED = "unchecked"
+    """The record does not settle it. Not a finding that the ordering is wrong."""
+    NOT_APPLICABLE = "not_applicable"
+    """The claim is not confirmatory, so there is no registration for it to postdate."""
+
+
+class OrderingReason(enum.StrEnum):
+    """Why an ordering check reached the outcome it did."""
+
+    RUN_FOLLOWS_REGISTRATION = "run_follows_registration"
+    RUN_PRECEDES_REGISTRATION = "run_precedes_registration"
+    NO_RUN_RECORD = "no_run_record"
+    NO_EVIDENCE_OFFERED = "no_evidence_offered"
+    """The claim names no evidence, so it names no artifact and no run can produce one. Separate
+    from `no_run_record`, which sends a reader looking for a run that should exist: here nothing
+    was offered to order against, and the fix is to declare evidence."""
+    NO_REGISTERED_PLAN = "no_registered_plan"
+    REGISTERED_PLAN_UNPINNED = "registered_plan_unpinned"
+    REGISTERED_PLAN_CHANGED = "registered_plan_changed"
+    RUN_OUTPUT_UNLINKED = "run_output_unlinked"
+    """The run names an artifact but records no digest for it, so a later file with the same
+    name can be presented as the output of an earlier run."""
+    RUN_OUTPUT_CHANGED = "run_output_changed"
+    TIMESTAMP_MISSING = "timestamp_missing"
+    AMBIGUOUS_PRODUCING_RUN = "ambiguous_producing_run"
+    NOT_CONFIRMATORY = "not_confirmatory"
+
+
+class RegistrationAuthority(enum.StrEnum):
+    """Who attests to the registration timestamp.
+
+    A hash and two self-recorded timestamps establish internal consistency, not chronology:
+    an actor who can write `registered_at`, `started_at` and the plan digest after seeing
+    results can manufacture an ordered history. Recording the authority makes that limit a
+    field rather than a caveat, and lets a policy require better than the weakest one.
+    """
+
+    SELF_RECORDED = "self_recorded"
+    GIT_REMOTE = "git_remote"
+    OSF = "osf"
+    ZENODO = "zenodo"
+    TRUSTED_TIMESTAMP = "trusted_timestamp"
+
+    @property
+    def rank(self) -> int:
+        return _AUTHORITY_RANK[self]
+
+
+_AUTHORITY_RANK = {
+    RegistrationAuthority.SELF_RECORDED: 0,
+    RegistrationAuthority.GIT_REMOTE: 1,
+    RegistrationAuthority.OSF: 2,
+    RegistrationAuthority.ZENODO: 2,
+    RegistrationAuthority.TRUSTED_TIMESTAMP: 3,
+}
+
+
+class Validity(enum.StrEnum):
+    """Whether a decision describes the artifact the manifest declared."""
+
+    AUTHORITATIVE = "authoritative"
+    UNPINNED_ARTIFACT = "unpinned_artifact"
+    """No digest was recorded, so the file read may not be the file meant."""
+    BROKEN_PIN = "broken_pin"
+    """The file read is provably not the file that was pinned. The comparison still ran and
+    its result is reported, marked non-authoritative, because a diagnostic is more useful than
+    a blank."""
+    ARTIFACT_ABSENT = "artifact_absent"
+    """Nothing exists at the declared path. No comparison ran, so no decision against this
+    artifact describes anything that was read."""
+
+
+class Reason(enum.StrEnum):
+    """Why an outcome obtained. Machine-readable, so a tool can route by cause."""
+
+    PASSAGE_PRESENT = "passage_present"
+    VALUE_MATCH = "value_match"
+    PASSAGE_ABSENT = "passage_absent"
+    VALUE_MISMATCH = "value_mismatch"
+    POINTER_ABSENT = "pointer_absent"
+    COLUMN_ABSENT = "column_absent"
+    ROW_ABSENT = "row_absent"
+    ROW_AMBIGUOUS = "row_ambiguous"
+    ROW_SELECTOR_INVALID = "row_selector_invalid"
+    SELECTOR_NOT_SCALAR = "selector_not_scalar"
+    """The locator resolved to a container. A list or mapping is not a value."""
+    FORMAT_UNSUPPORTED = "format_unsupported"
+    """No adapter addresses this format. Reported rather than approximated: falling back to
+    searching the file for the printed number would find it wherever it appears and call
+    that verification."""
+    WRONG_PAGE = "wrong_page"
+    """The passage occurs in the artifact, on a different page than the one asserted."""
+    VALUE_NOT_NUMERIC = "value_not_numeric"
+    PLACES_MISMATCH = "places_mismatch"
+    """The assertion declares how many decimal places the manuscript reports the value to,
+    and the value as printed is written to another number. Distinct from `value_mismatch`
+    because the file is not what disagrees: the two statements about the manuscript do, and
+    the fix is in the manuscript or in the declaration."""
+    PASSAGE_AMBIGUOUS = "passage_ambiguous"
+    """One pair of prose anchors selected two different values, so the document states two
+    numbers where the assertion addresses one. Reported rather than resolved to the first: a
+    document contradicting itself is a finding."""
+    NUMBER_AS_WORD = "number_as_word"
+    """The locator selected an English cardinal written out, under a locator that did not ask
+    for one. Distinct from `value_not_numeric` because the fix is different: the value is
+    there and a reader would call it a number, so an author told only that no number was found
+    goes looking for a broken anchor."""
+    QUOTATION_AMBIGUOUS = "quotation_ambiguous"
+    """The quoted passage occurs more than once in the artifact, and the record does not say
+    which occurrence it means. Distinct from `passage_ambiguous`, which says the document states
+    two different numbers: a passage written twice contradicts nothing, and the fix is a
+    `prefix` or `suffix` on the quote assertion, naming the text on either side of the
+    occurrence meant, not an edit to the document. A `prefix` or `suffix` that singles out no
+    occurrence leaves this reason standing. The two shared a reason
+    after `citations`' `ambiguous` state, which `repro verify` reported as `KeyError: 'ambiguous'`
+    under 0.4.2, was first mapped."""
+    EXTRACTORS_DISAGREE = "extractors_disagree"
+    """Two extractors that both read the artifact disagree about whether the passage is in it.
+    Distinct from `passage_absent`, which says the artifact was read and does not contain it --
+    an accusation against the manuscript. This one accuses nothing and asks for a better reader,
+    and it shared `passage_ambiguous` until an author was told a document contradicted itself
+    when the real answer was that two readers of it did."""
+    EXTRACTOR_MISSING = "extractor_missing"
+    ARTIFACT_MISSING = "artifact_missing"
+    ARTIFACT_UNREADABLE = "artifact_unreadable"
+    ARTIFACT_UNDECLARED = "artifact_undeclared"
+    BACKEND_DEFECT = "backend_defect"
+    NOT_OFFERED = "not_offered"
+
+
+class Warning_(enum.StrEnum):
+    """Notes about the evidence itself, orthogonal to the outcome."""
+
+    SHORT = "short"
+    TRUNCATED = "truncated"
+    NORMALIZED = "normalized"
+    WRONG_PAGE = "wrong_page"
+    PAGE_UNCHECKED = "page_unchecked"
+    """The quote assertion declares a `page`, the passage was found, and nothing checked the
+    page: the artifact is not read page by page, or the passage matched only with spacing
+    ignored. The passage is in the artifact, so the assertion is `verified`; the page is
+    neither confirmed nor refuted, and a policy grades it as it grades a check that did not
+    run."""
+    POSITIONAL_ADDRESS = "positional_address"
+    """Addressed by row index, which names a different cell if the table is reordered."""
+
+
+class Tie(BaseModel):
+    """A compared value exactly halfway between two values at the comparison precision.
+
+    Rounding half up prints one neighbor and rounding half to even may print the other, and
+    software is divided between the two, so a manuscript printing either has rounded
+    correctly. Both verify. The record says that it was a tie, so the acceptance is visible
+    and is not mistaken for an ordinary agreement.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    lower: str
+    upper: str
+    """The two values the compared one lies halfway between, at the printed precision."""
+
+    printed: str
+    """The value the manuscript prints. `lower` or `upper` where the assertion verified, and
+    neither where it is a mismatch."""
+
+
+class DecisionSide(BaseModel):
+    """What one side of a two-sided assertion read, and where it read it.
+
+    `Decision` names one artifact and one locator, which is all a `metric` or a `quote` has.
+    A correspondence reads two, and recording only one would leave half the decision unbound:
+    the locator digest exists so a selector edited after the fact changes the record, and a
+    selector nothing records is a selector nothing binds.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    artifact_id: str
+    artifact_digest: str | None = None
+    locator_digest: str | None = None
+    validity: Validity = Validity.AUTHORITATIVE
+    extracted: str | None = None
+    """The value read, in the representation the artifact used. `None` where this side did
+    not extract, which is why the decision reports no comparison."""
+
+    conversion: Conversion | None = None
+    """The conversion this side declares, or None."""
+
+    converted: str | None = None
+    """`extracted` under `conversion`, which is the value compared. None where no conversion
+    is declared, or where the side read no number to convert."""
+
+    extraction_digest: str = ""
+    """sha256 of what this side's extractor produced. `unknown` where the side produced
+    nothing to hash.
+
+    Per side rather than per decision because the decision-level digest covers both
+    extractions at once and so cannot say which of the two moved, and a correspondence exists
+    to be told which of two artifacts changed."""
+
+
+class DecisionMember(BaseModel):
+    """What one member of an aggregate read, and where it read it.
+
+    One per member, in the order the manifest lists them, so a report can show every value
+    the statistic was computed over and a deleted or edited member changes the record.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    artifact_id: str
+    artifact_digest: str | None = None
+    locator_digest: str | None = None
+    validity: Validity = Validity.AUTHORITATIVE
+    extracted: str | None = None
+    """The value read, in the representation the artifact used. `None` where this member did
+    not extract, which is why the decision reports no comparison."""
+
+    converted: str | None = None
+    """`extracted` under the assertion's `conversion`, which is the value the statistic is
+    over. None where no conversion is declared, or where a member read no number."""
+
+    extraction_digest: str = ""
+    """sha256 of what this member's extractor produced. `unknown` where it produced nothing
+    to hash."""
+
+
+class Decision(BaseModel):
+    """The outcome of evaluating one evidence assertion. Frozen: a decision that can be
+    edited after the fact records nothing."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    claim_id: str
+    claim_digest: str
+    kind: str
+
+    execution: ExecutionStatus
+    extraction: ExtractionStatus
+    comparison: ComparisonStatus
+    reason: Reason
+    detail: str = ""
+
+    validity: Validity = Validity.AUTHORITATIVE
+    artifact_id: str = ""
+    artifact_digest: str | None = None
+    """The digest of the bytes actually read, so the decision can be re-checked against the
+    same content rather than the same path."""
+
+    locator_digest: str | None = None
+    """The digest of the canonical locator, so a decision binds how the value was addressed
+    as well as what was read. A selector edited after the fact changes this even where the
+    artifact is untouched."""
+
+    extracted: str | None = None
+    """The value read from the one artifact, in the representation the artifact used. None
+    where no value was read, and for a kind that reads no value or reads two: a
+    `correspondence` records what each side read in `sides`."""
+
+    conversion: Conversion | None = None
+    """The conversion the assertion declares, or None."""
+
+    converted: str | None = None
+    """`extracted` under `conversion`, which is the value compared with the printed one. None
+    where no conversion is declared, or where no number was read to convert."""
+
+    tie: Tie | None = None
+    """Set where the compared value lay exactly halfway between two values at the printed
+    precision. None otherwise, and under `absolute` and `relative`, which round nothing."""
+
+    sides: tuple[DecisionSide, ...] = ()
+    """The two values a `correspondence` compared, each with the artifact and locator it came
+    from. Empty for every kind that reads one artifact, which records its single artifact and
+    locator in the fields above."""
+
+    members: tuple[DecisionMember, ...] = ()
+    """The values an `aggregate` was computed over, each with the artifact and locator it
+    came from. Empty for every other kind."""
+
+    statistic: Statistic | None = None
+    """What an `aggregate` computed over `members`. None for every other kind."""
+
+    computed: str | None = None
+    """The statistic of the members' values, which is what was compared with the printed
+    value. Written exactly where it is a terminating decimal, and otherwise rounded half-even
+    to three places past the precision the manuscript prints; the comparison is made on the
+    exact value either way. None where a member held no number."""
+
+    backend: str = ""
+    backend_version: str = ""
+    """The protocol version of the backend's interface. Named because the same inputs can
+    receive different decisions after a backend upgrade, and a stored decision that does not
+    say which backend produced it cannot be compared with a later one. It says nothing about
+    the program that read the artifact; `tool_version` does."""
+
+    tool: str = ""
+    """What performs the extraction: `pdftotext` for a quotation, the distribution supplying
+    the format adapters for a value. A separate field from `backend_version` because the two
+    move independently -- an extractor upgraded under a backend that did not change reads a
+    ligature or a column differently while the protocol version stays where it was."""
+
+    tool_version: str = ""
+    """The version `tool` reports, as it reports it, or `unknown` where it could not be
+    interrogated. Empty only on a decision no backend produced: a version that was sought and
+    not obtained has to be distinguishable from one that was never sought."""
+
+    extraction_digest: str = ""
+    """sha256 of what the extractor produced -- the whole extracted text for a quotation, the
+    extracted value for a number. `tool_version` catches drift that announces itself; this
+    catches drift from any cause, including a rebuilt binary reporting the same version and an
+    environment that changes an encoding path. `unknown` where the extraction produced nothing
+    to hash, empty only on a decision no backend produced.
+
+    Recorded and not enforced. Whether a changed extraction invalidates a stored decision the
+    way a changed artifact does is a policy question, and `claims.policy` decides policy."""
+
+    warnings: tuple[Warning_, ...] = ()
+
+    @property
+    def outcome(self) -> Outcome:
+        if self.execution is ExecutionStatus.FAILED:
+            return Outcome.ERROR
+        if self.execution is ExecutionStatus.UNAVAILABLE:
+            return Outcome.UNCHECKED
+        if self.extraction in (ExtractionStatus.ABSENT, ExtractionStatus.INVALID):
+            return Outcome.NOT_FOUND
+        if self.comparison is ComparisonStatus.MATCH:
+            return Outcome.VERIFIED
+        if self.comparison is ComparisonStatus.MISMATCH:
+            return Outcome.MISMATCH
+        return Outcome.UNCHECKED
+
+    @property
+    def is_authoritative(self) -> bool:
+        return self.validity is Validity.AUTHORITATIVE