Checks

def add_checks(
    graph: Graph, rubric: Rubric, results: Sequence[Result], versions: Mapping[str, str]
) -> tuple[Graph, dict[str, bytes], list[dict[str, Any]]]:
    """Add each result to a graph as a check node with its check edge, numbered after the graph's checks.

    A check node ``c-NNN`` takes the first number the graph does not have. Its ``attributes.check`` is
    the check record, and ``attributes.observed`` is ``true`` for a pass and ``false`` for a fail; an
    errored check has no ``observed``. The edge ``target --observes--> c-NNN`` carries the check type's
    ``sensitivity`` and ``false_pass``. Verdicts are not set: ``assess`` derives them.

    Args:
        graph: The graph.
        rubric: The rubric, which declares every result's check type.
        results: The results, in the order they are numbered.
        versions: The versions of the code that ran the checks, by name, as ``session.versions`` gives them.

    Returns:
        The graph with the checks; the files of each check's directory, by path in the run; and one
        entry per check: its id, type, target and result.
    """
    fresh = (node_id for n in count(1) if (node_id := f"c-{n:03d}") not in graph)
    nodes: list[Node] = []
    relations: list[Relation] = []
    files: dict[str, bytes] = {}
    report = []
    for result in results:
        check_id = next(fresh)
        check: Check = rubric.checks[result.type]
        tool = {
            "name": "credencegraph-extract",
            "version": versions.get("credencegraph-extract"),
            "python": versions.get("python"),
            **{library: versions.get(library) for library in result.libraries},
        }
        record, check_files = _record(check_id, result, tool)
        files.update({f"{CHECKS}/{check_id}/{name}": data for name, data in check_files.items()})
        attributes: dict[str, Any] = {"origin": EVIDENCE, "check": record}
        if result.result != ERROR:
            attributes["observed"] = result.result == PASSED
        nodes.append(
            Node(
                check_id,
                kind=result.type,
                statement=f"{result.type} on {result.target}: {result.result}",
                sources=result.sources,
                attributes=attributes,
            )
        )
        relations.append(
            Relation(
                f"{result.target}-{OBSERVES}-{check_id}",
                OBSERVES,
                result.target,
                check_id,
                sensitivity=check.sensitivity,
                false_pass=check.false_pass,
            )
        )
        report.append({"id": check_id, "type": result.type, "target": result.target, "result": result.result})
    out = Graph()
    for node in (*graph, *nodes):
        out.add_node(node)
    for relation in (*graph.relations.values(), *relations):
        out.add_relation(relation)
    return out, files, report

def applicable(rubric: Rubric, kind: str) -> list[str]:
    """Return the check types the model may propose for a node type: proposed by the runner, declared and targeting it.

    Args:
        rubric: The rubric.
        kind: The node type.

    Returns:
        The check type names, in the order of ``PROPOSED``.
    """
    return [name for name in PROPOSED if name in rubric.checks and kind in rubric.checks[name].targets]

def assess(graph: Graph, rubric: Rubric) -> Graph:
    """Set the verdict of every node the checks assess, from the checks that observe it.

    A target's verdict comes from the results of the check nodes its ``observes`` relations lead to,
    never from a model: ``fails``, ``holds`` or ``undetermined`` as ``verdict`` gives it, else
    ``not_assessed`` because no implemented check type may run on the node, or none was run.

    Args:
        graph: The graph.
        rubric: The rubric.

    Returns:
        The graph with ``attributes.assessment`` set on every target.
    """
    by_target: dict[str, list[str]] = {}
    for relation in graph.relations.values():
        check = graph.nodes[relation.target].attributes.get("check") if relation.type == OBSERVES else None
        if isinstance(check, Mapping):
            by_target.setdefault(relation.source, []).append(check.get("result"))
    assessed = set(targets(graph, rubric))
    out = Graph()
    for node in graph:
        if node.id in assessed:
            found = verdict(by_target.get(node.id, []))
            if found is not None:
                assessment: dict[str, Any] = {"verdict": found}
            else:
                reason = NOT_SELECTED if applicable(rubric, node.kind) else NO_CHECK
                assessment = {"verdict": NOT_ASSESSED, "reason": reason}
            node = replace(node, attributes={**node.attributes, "assessment": assessment})  # noqa: PLW2901
        out.add_node(node)
    for relation in graph.relations.values():
        out.add_relation(relation)
    return out

def citation_refusal(graph: Graph, rubric: Rubric, target: Any, reference: Any) -> dict[str, Any] | None:
    """Refuse a citation check the check pass would refuse, or one on a target whose citation check already passed or failed.

    The target must be a node the rubric runs ``citation-support`` on, and it, or a node it is part of,
    must cite the reference, a bibliography entry of the document. A citation check that passed or
    failed stays: another on the same target is refused. One that erred moved no credence, so another
    may follow it.

    Args:
        graph: The graph.
        rubric: The rubric.
        target: The node the check bears on.
        reference: The id of the bibliography entry.

    Returns:
        The rejection, with its code, message, record and, where the refusal knows what to change, a
        ``fix``; or ``None`` when the check may run.
    """
    record = {"target": target, "type": CITATION, "reference": reference}
    try:
        _plan(graph, rubric, record)
        settled = [
            node.id
            for node in graph
            if isinstance(check := node.attributes.get("check"), Mapping)
            and check.get("type") == CITATION
            and check.get("target") == target
            and check.get("result") != ERROR
        ]
        if settled:
            msg = f"{target!r} has the citation check {settled[0]}, which passed or failed: it stays"
            raise _ProposalError(
                DUPLICATE_RECORD, msg, f"leave {target!r}: a citation check runs again only after one that errs"
            )
    except _ProposalError as refused:
        rejection = {"node": target if isinstance(target, str) else None, "code": refused.code, "message": str(refused)}
        rejection["record"] = record
        if refused.fix is not None:
            rejection["fix"] = refused.fix
        return rejection
    return None

def directory_digest(files: Mapping[str, bytes]) -> str:
    """Return the digest of a check's directory: of one line ``<name> <digest>`` per file, sorted by name.

    Args:
        files: The files by name.

    Returns:
        The digest.
    """
    listing = "".join(f"{name} {bytes_digest(files[name])}\n" for name in sorted(files))
    return bytes_digest(listing.encode("utf-8"))

def fix(code: str, record: Any) -> str | None:
    """Say what to change in a refused proposal, as an instruction to the model, or ``None`` beyond the error.

    Args:
        code: The rejection code.
        record: The proposal.

    Returns:
        The instruction.
    """
    nodes = record.get("nodes") if isinstance(record, Mapping) else None
    label_fix = _label_fix(code, record)
    if label_fix is not None:
        return label_fix
    if code == UNFAITHFUL:
        return (
            f"write every number, the expected value included, exactly as a numeral the text of {nodes} writes, "
            "and add to nodes any chunk whose numeral you use; a constant no cited chunk writes, such as the 1 of "
            "1 - p or a 100, is not allowed: rewrite the expression without it, as a - a * p rather than "
            "a * (1 - p), where a and p are numerals the text writes"
        )
    return _FIXES.get(code)

def judged(  # noqa: PLR0913 - the check, what was read, what the agent said, and how it is tied
    graph: Graph,
    target: str,
    reference: str,
    observation: Mapping[str, Any],
    *,
    passage: str,
    supports: bool,
    untied: str | None,
    model: str | None,
) -> Result:
    """Return the result of a citation check from what the tool read and what the agent judged.

    The check is an ``error`` when the quoted passage is not in the source's text, or when the source
    is not tied to the reference (``untied`` says why): an errored check moves no credence. Otherwise
    it passes when the agent judged that the passage supports the target, and fails when not.

    Args:
        graph: The graph.
        target: The citing node.
        reference: The bibliography entry.
        observation: What the tool read: ``citation.read_cited`` or ``citation.read_url``.
        passage: The passage the agent quoted.
        supports: The agent's judgement.
        untied: Why the source is not tied to the reference, or ``None``.
        model: The model the call reported.

    Returns:
        The result.
    """
    document = _document(observation)
    source = (
        {"file": observation.get("file")}
        if observation.get("kind") == "cited"
        else {
            "url": observation.get("url"),
            "final_url": observation.get("final_url"),
        }
    )
    artifact: dict[str, Any] = {
        "kind": "citation",
        "reference": reference,
        "document": document,
        "source": source,
        "tied": untied is None,
    }
    inputs = {"statement": node_text(graph, graph.nodes[target]), "source_digest": observation.get("text_digest")}
    output = {"passage": passage, "supports": supports, "read": dict(observation)}
    reported = {"model": model}
    found = observation.get("found")
    if not isinstance(found, list):
        detail = "the quoted passage is not in the text of the source"
        return Result(CITATION, target, artifact, inputs, ERROR, detail, output, model=reported)
    quote = normalise_text(passage)
    locator = f"chars={found[0]}-{found[1]}"
    artifact.update(locator=locator, quote=quote, digest=text_digest(quote))
    if untied is not None:
        detail = f"source not tied to the reference: {untied}"
        return Result(CITATION, target, artifact, inputs, ERROR, detail, output, model=reported)
    anchor = SourceAnchor(document, locator, quote, text_digest(quote))
    result = PASSED if supports else FAILED
    detail = f"the passage at {locator} {'supports' if supports else 'does not support'} the statement"
    return Result(CITATION, target, artifact, inputs, result, detail, output, (anchor,), model=reported)

def plain(value: Any) -> Any:
    """Return a value as JSON gives it back: a graph's read-only mappings and its tuples become dicts and lists.

    Args:
        value: A value made of JSON types, mappings and sequences.

    Returns:
        The value in JSON types only.
    """
    return json.loads(json.dumps(value, default=lambda item: dict(item) if isinstance(item, Mapping) else list(item)))

def rerun(graph: Graph, rubric: Rubric, check: Node) -> tuple[dict[str, Any], dict[str, bytes]]:
    """Run a recorded deterministic check again, from the inputs its record holds.

    The recorded inputs are checked as the run checked the proposal, numeral faithfulness included,
    and evaluated by the current code; ``rederive-maths-numeric`` draws its points again from the
    encoding's seed. A record that can no longer be run gives the result ``error``, with the reason as
    its detail.

    Args:
        graph: The graph the check node is in.
        rubric: The rubric of the run.
        check: A check node of a type in ``DETERMINISTIC``.

    Returns:
        The check record the re-run gives, with the recorded ``tool``, and the files of its directory
        by name. When the code and the record agree, the record equals ``check.attributes["check"]``.

    Raises:
        ValueError: If the node is not a check of a type in ``DETERMINISTIC``.
    """
    recorded = plain(check.attributes.get("check"))
    if not isinstance(recorded, dict) or recorded.get("type") not in DETERMINISTIC:
        msg = f"{check.id!r} is not a check of a type in {list(DETERMINISTIC)}"
        raise ValueError(msg)
    check_type, target = recorded["type"], recorded.get("target")
    artifact, inputs = recorded.get("artifact"), recorded.get("inputs")
    if not isinstance(artifact, dict) or not isinstance(inputs, dict):
        artifact, inputs = {}, {}
    # The proposal the record was run from: the symbolic encoding for both maths checks.
    proposed = RECOMPUTE if check_type == RECOMPUTE else REDERIVE
    proposal = {key: inputs.get(key) for key in _ALLOWED[proposed]}
    proposal.update(target=target, type=proposed, nodes=artifact.get("nodes"))
    try:
        plan = _plan(graph, rubric, proposal)
    except _ProposalError as refused:
        detail = f"the recorded inputs cannot be run: {refused}"
        result = Result(check_type, str(target), artifact, inputs, ERROR, detail, {"result": ERROR})
    else:
        if check_type == RECOMPUTE:
            result = _recompute(graph, plan)
        elif check_type == REDERIVE:
            result = _rederive(plan)
        else:
            result = _numeric(plan, artifact)
    return _record(check.id, result, recorded.get("tool") or {})

def run_maths(
    graph: Graph, rubric: Rubric, proposals: Sequence[Any], versions: Mapping[str, str]
) -> tuple[Graph, dict[str, bytes], list[dict[str, Any]], list[dict[str, Any]]]:
    """Check and run proposals of the maths check types, one tool call's worth, after the checks a graph has.

    Each proposal is checked (``_plan``), in the order given, and is refused when it
    repeats the target and type of a check the graph has or an earlier proposal, or the same step on
    another target (``_admit``). A ``citation-support`` proposal is refused: the citation tool runs it.
    The admitted ones run in the order given; a ``rederive-maths`` that errs is followed by its numeric
    fallback when the rubric declares one. Verdicts are not set.

    Args:
        graph: The graph, with the checks already run.
        rubric: The rubric.
        proposals: The proposals.
        versions: The versions of the code that runs them.

    Returns:
        The graph with the new checks; the files of their directories; each new check's id, type,
        target, result and detail; and the refused proposals, each with its code, message and, where
        the refusal knows what to change, a ``fix``.
    """
    plans: list[_Plan] = []
    rejections: list[dict[str, Any]] = []
    for record in proposals:
        if isinstance(record, Mapping) and record.get("type") == CITATION:
            target = record.get("target")
            rejections.append(
                {
                    "node": target if isinstance(target, str) else None,
                    "code": INVALID_RECORD,
                    "message": f"a {CITATION} check is not run with the maths checks",
                    "record": record,
                    "fix": f"send a {CITATION} check to the citation tool, with the source and the passage",
                }
            )
            continue
        rejections.extend(_admit(graph, rubric, [record], plans))
    results = [result for plan in plans for result in _maths(graph, rubric, plan)]
    out, files, report = add_checks(graph, rubric, results, versions)
    checks = [{**entry, "detail": result.detail} for entry, result in zip(report, results, strict=True)]
    return out, files, checks, rejections

def targets(graph: Graph, rubric: Rubric) -> list[str]:
    """Return the nodes the checks assess: document and analyst nodes of a type with ``assess = true``.

    Args:
        graph: The graph.
        rubric: The rubric.

    Returns:
        Their ids, in document order.
    """
    return [
        node.id
        for node in graph
        if origin_of(node) in (DOCUMENT, ANALYST) and (spec := rubric.types.get(node.kind)) is not None and spec.assess
    ]

def verdict(results: Sequence[str]) -> str | None:
    """Return the verdict the results of a node's checks give, or ``None`` when no check ran.

    Args:
        results: The results.

    Returns:
        ``fails`` if any failed, else ``holds`` if any passed, else ``undetermined``.
    """
    if not results:
        return None
    if FAILED in results:
        return FAILS
    return HOLDS if PASSED in results else UNDETERMINED