cadrumo.core.citation_grounding module

Whether a citation’s quotation was read against the corpus, refused, or unreachable.

A citation carries a document pointer, a locator and — when it can — the verbatim text that makes the pointer checkable. This enum is the record of which of those the citation actually has, and it lives in core because two registry corpora now depend on the same distinction: the IVA catalogue, where it was first drawn, and the spending-category profiles.

The distinction is the point. An unverified citation, one examined and found unsupportable, and one whose source is not bundled at all look identical when all three simply lack text. Both corpora spent their whole lives in that undifferentiated state: every quotation was a translation key resolving to the literal word “Quote” or “Quoted text”, so nothing could tell a grounded citation from an ungrounded one.

The states are deliberately not ranked. VERIFIED is the only one that asserts evidence; the other two are different REASONS for its absence, and collapsing them would restore exactly the ambiguity this enum exists to remove.

class CitationGrounding(*values)

Bases: StrEnum

What a citation’s record actually holds in place of its quotation.

VERIFIED

The quotation was read from the bundled corpus and supports the claim.

A citation in this state MUST carry its verbatim text, and the text MUST occur in the normalised corpus of its own legal reference. This is the only state that asserts checkable evidence.

UNRESOLVED

the cited provision does not support the claim.

Not “not yet checked”. A citation carrying this has been read against the corpus and the reason it failed is recorded beside it.

Type:

Examined and refused

SOURCE_NOT_BUNDLED

The cited source is authoritative but is not in the bundled corpus.

Distinct from UNRESOLVED in the direction of the failure, which is why it is a third state rather than a reuse of the second. An unresolved citation was checked and found wanting; this one COULD NOT be checked, because the document it names — an AEAT Manual práctico edition, a portal help page — is not among the consolidated BOE texts shipped with the application, so no verbatim excerpt can be transcribed from anything the repository holds.

Labelling such a citation UNRESOLVED would assert that its provision was read and rejected, which is a claim about the law nobody made. Labelling it VERIFIED with invented text would be worse: it would manufacture the evidence the state exists to say is missing. The honest record is that the pointer stands and the excerpt is unreachable from here.