orthonym.assembly.coverage_audit#

Note

Internal API. Names and behaviour may change between releases.

Producer-agnostic coverage verdict for the _finish choke (a phase L0/L1).

Two carrier-specific proofs feed ONE verdict:

  • GeneralEngineResult (has .bindings) -> certify_general_result (E1 + binding spine, Java-free atom->token partition).

  • bare str (PIN handlers) -> reuse the verdict ALREADY computed by _final_opsin_validity_gate for this exact name (the CARRIED RULING in task-L0-brief.md: already OPSIN-parses every PIN name, so a second OPSIN call per name would ~2x default-path cost). Only when no

    result is available for this name (e.g. a tier/path that skipped

    the gate) does this fall back to a fresh OPSIN re-anchor (validate_atom_coverage, the (mol, name) InChIKey-skeleton compare).

This is a coverage AUDIT; L0 runs it SHADOW (telemetry only, never changes the returned name), L1 (a later task) turns it into a veto.

HONEST LIMIT: the bare-str path depends on OPSIN (not Java-free); it is the de-facto PIN coverage proof already applies. A Java-free PIN certificate is out of scope (phase4b Gap-1).

class orthonym.assembly.coverage_audit.CoverageVerdict(complete, method, detail='')#

Bases: object

The producer-agnostic coverage verdict for one emitted name.

Variables:

  • complete (bool) – True iff the winner’s proof shows it accounts for every heavy atom (and, on the GER path, bond/charge) of the input.

  • method (str) – which proof produced this verdict – one of "e1_spine" (GeneralEngineResult, certify_general_result), "self01" (bare str, reused verdict – no extra OPSIN call), "reanchor" (bare str, a fresh OPSIN re-anchor because no verdict was available), "unavailable" (no proof could be made – OPSIN absent/erroring; fails OPEN in SHADOW).

  • detail (str) – free-text diagnostic, empty on a clean pass.

complete: bool#
method: str#
detail: str = ''#
orthonym.assembly.coverage_audit.audit_coverage(mol, name, result_obj, self01_complete=None, skip_reanchor=False, skip_detail='')#

Return the coverage verdict for the winning name of mol.

Parameters:

  • mol – RDKit Mol for the input structure.

  • name (str) – the name string about to ship (or that shipped).

  • result_obj – the GeneralEngineResult that produced name, if the winner came from the general engine (has a .bindings attribute); None for every bare-str (PIN/T4/etc.) winner.

  • self01_complete (bool | None) – the verdict ALREADY computed for this exact name by _final_opsin_validity_gate (True = OPSIN re-parsed it to the same constitution, False = a verified mismatch), or None when no such verdict exists for this name (a path that skipped the gate, or the gate’s outcome belonged to a different string – see metrics.provenance.resolve_gate_outcome). IGNORED when result_obj is not None (the GER path never needs it – E1 is Java-free and strictly more informative: it covers bonds/charge, not merely constitution).

  • skip_reanchor (bool) – a phase L0 review fix (C1/C2). When True (and self01_complete is None), skip the validate_atom_coverage re-anchor ENTIRELY – no OPSIN subprocess is spawned – and return complete=True, method="unavailable" directly. Set by the caller when a fresh re-anchor is GUARANTEED useless: a carve-out PIN name is OPSIN-unparseable BY DESIGN (thioperoxol/inositol/np_stereoparent/ dianhydride/…/halogen_uide), and a gate outcome of disabled/unavailable/not_run means no real gate decision exists to reuse or repeat. Ignored when self01_complete is not None (a real verdict always wins) and ignored on the GER path.

  • skip_detail (str) – the:class:CoverageVerdict detail to use when skip_reanchor fires; defaults to a generic message.

Returns:

A:class:CoverageVerdict. Fail-closed (complete=False) on an exception in the GER path; fail-OPEN (complete=True, method="unavailable") on an exception, OPSIN-unavailable, or skip_reanchor in the bare-str path – SHADOW must never break a name, and must never spawn a guaranteed-useless OPSIN subprocess.

Return type:

CoverageVerdict