Enum ContrastiveDataError 

#[non_exhaustive]
pub enum ContrastiveDataError {
    MalformedRow {
        split: String,
        index: usize,
        reason: String,
    },
    InvalidUtf8 {
        split: String,
        index: usize,
    },
    EmptyInput {
        split: String,
        index: usize,
    },
    UnknownLabel {
        split: String,
        index: usize,
        label: usize,
    },
    LabelTextMismatch {
        split: String,
        index: usize,
        label: usize,
        expected_text: String,
        got_text: String,
    },
    InvalidClassCounts {
        split: String,
        expected: Vec<usize>,
        got: Vec<usize>,
    },
    DeclaredLabelMapMismatch {
        split: String,
        shared: Vec<String>,
        got: Vec<String>,
    },
    DuplicateId {
        split: String,
        id: String,
    },
    ConflictingSourceRole {
        declared: String,
        embedded: String,
    },
    SplitRoleMismatch {
        expected_role: String,
        embedded_role: String,
    },
    RowHashMismatch {
        id: String,
        expected: String,
        got: String,
    },
    CrossSplitDuplicateUnderflow {
        class_label: usize,
        pool: usize,
        shots: usize,
    },
    InvalidShots {
        got: usize,
        allowed: &'static str,
    },
    SemanticHashMismatch {
        expected: String,
        got: String,
    },
    SelectionReplayMismatch {
        field: String,
    },
    EndpointNotInSelection {
        id: String,
        found_in: String,
    },
    ProfileMismatch {
        expected: String,
        got: String,
    },
    MissingSplit {
        role: String,
    },
    SplitHashMismatch {
        split: String,
        expected: String,
        got: String,
    },
    FingerprintMismatch {
        expected: String,
        got: String,
    },
    ExclusionRecordMismatch {
        expected: String,
        got: String,
    },
    SelfPair {
        id: u64,
    },
    NoPairCapacity {
        positive_capacity: u64,
        negative_capacity: u64,
    },
    ZeroBudget,
    ZeroHardCap,
    BudgetExceedsHardCap {
        budget: u64,
        hard_cap: u64,
    },
    BudgetExceedsCapacity {
        budget: u64,
        capacity: u64,
    },
    OrdinalOutOfRange {
        ordinal: u64,
        budget: u64,
    },
    PairTargetMismatch {
        lo: String,
        hi: String,
        declared_target: f32,
        derived_target: f32,
    },
    UnsupportedSchemaVersion {
        field: String,
        got: u32,
        supported: u32,
    },
    UnsupportedNormalizationVersion {
        got: String,
        supported: &'static str,
    },
    UnsupportedPolicyVersion {
        policy: String,
        got: u32,
        supported: u32,
    },
    UnsupportedAlgorithmVersion {
        got: u32,
        supported: u32,
    },
    ArithmeticOverflow {
        operation: String,
    },
    Serialization {
        context: String,
        detail: String,
    },
    Io {
        context: String,
        detail: String,
    },
}

Every way the contrastive data protocol can refuse to proceed.

Grouped below by the boundary that raises them: split ingest, selection and manifest, dataset attestation, pair construction, and version/arithmetic/plumbing.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

MalformedRow

A JSONL row did not parse, or parsed into something the schema rejects.

Fields

split: String

Split role name as declared by the caller (train, validation, …).

index: usize

Zero-based row index within the split’s buffer.

reason: String

Why the row was rejected (parser message or schema violation).

InvalidUtf8

A row’s bytes are not valid UTF-8, so they were never parsed.

Fields

split: String

Split role name as declared by the caller.

index: usize

Zero-based row index within the split’s buffer.

EmptyInput

A row’s input field is empty or whitespace-only.

Fields

split: String

Split role name as declared by the caller.

index: usize

Zero-based row index within the split’s buffer.

UnknownLabel

A row’s numeric label is outside the declared label map.

Fields

split: String

Split role name as declared by the caller.

index: usize

Zero-based row index within the split’s buffer.

label: usize

The out-of-range label value read from the row.

LabelTextMismatch

A row’s label_text disagrees with label_names[label].

This is a distinct failure from Self::UnknownLabel: the numeric label is in range, but the human-readable text contradicts it, which is exactly what a tampered or hand-edited mirror looks like.

Fields

split: String

Split role name as declared by the caller.

index: usize

Zero-based row index within the split’s buffer.

label: usize

The numeric label carried by the row.

expected_text: String

The text the declared label map assigns to label.

got_text: String

The text the row actually carried.

InvalidClassCounts

The per-class row counts of a split do not match the declaration.

Fields

split: String

Split role name as declared by the caller.

expected: Vec<usize>

Per-class counts the declaration requires.

got: Vec<usize>

Per-class counts actually observed.

DeclaredLabelMapMismatch

A per-split label map disagrees with the declaration’s shared label map.

The declaration carries one label map per split AND a shared one. Rows are validated against the per-split map, while the shared map is what reaches the fingerprint, the stored map and SelectionPayload::label_names. If the two disagree, every row validates and the manifest still commits a map that contradicts them, so the disagreement must be refused before any row is read.

Fields

split: String

Split role name whose declared map diverges.

shared: Vec<String>

The shared label map the manifest would commit.

got: Vec<String>

The map that split’s rows were validated against.

DuplicateId

The same row identifier appears twice inside one split.

Fields

split: String

Split role name as declared by the caller.

id: String

The identifier that appeared more than once.

ConflictingSourceRole

A dataset profile declared by the caller conflicts with the one in the bytes.

Fields

declared: String

Role the caller asserted when constructing the split.

embedded: String

Role embedded in the row payloads.

SplitRoleMismatch

A row’s embedded source_split is not the role being constructed.

The typestate makes leakage inexpressible for a library caller; this variant is what stops honest-looking bytes from object storage becoming a Split<Train> the compiler is perfectly happy with (D-16).

Fields

expected_role: String

Role being constructed.

embedded_role: String

Role found inside the row.

RowHashMismatch

A row’s recomputed content hash disagrees with the attested one.

Fields

id: String

The row identifier whose hash disagreed.

expected: String

Hex digest recorded in the attestation.

got: String

Hex digest recomputed from the supplied bytes.

CrossSplitDuplicateUnderflow

Cross-split duplicate exclusion shrank a class pool below shots_per_class.

Duplicate content is never fatal at prepare time (D-18, upheld verbatim by D-27) — it is excluded and recorded. This variant is the one real failure: after exclusion the pool can no longer supply the requested shots.

Fields

class_label: usize

The class whose pool ran short.

pool: usize

Rows remaining in the class pool after exclusion.

shots: usize

Shots per class the selection requested.

InvalidShots

shots_per_class is not one of the contracted values.

Checked BEFORE any RNG draw, so an invalid request never consumes an ordinal and never produces a partially built selection.

Fields

got: usize

The requested shots-per-class value.

allowed: &'static str

The contracted set, rendered for the message (e.g. {8, 16, 32, 64}).

SemanticHashMismatch

A selection manifest’s recorded semantic_hash does not match its payload.

Fields

expected: String

Digest recorded in the manifest envelope.

got: String

Digest recomputed from the canonical payload bytes.

SelectionReplayMismatch

Replaying a selection from its manifest did not reproduce the manifest.

Fields

field: String

The first field that disagreed (ordering, balance, membership, …).

EndpointNotInSelection

A pair endpoint names an identifier that is not in the selection.

This is D-27’s fail-closed span check for untrusted, replayed pair bytes.

Fields

id: String

The offending identifier, named so the failure is diagnosable.

found_in: String

Where the identifier WAS found, if anywhere (validation, nowhere, …).

ProfileMismatch

The attested dataset profile is not the one the consumer asked for.

Fields

expected: String

Profile the consumer requires.

got: String

Profile the attestation carries.

MissingSplit

The attestation names a split role for which no bytes were supplied.

Fields

role: String

The split role that is absent.

SplitHashMismatch

A split’s recomputed JSONL digest disagrees with the attested one.

Fields

split: String

Split role name.

expected: String

Digest recorded in the attestation.

got: String

Digest recomputed from the supplied buffer.

FingerprintMismatch

The recomputed dataset fingerprint disagrees with the attested one.

Fields

expected: String

Fingerprint recorded in the attestation.

got: String

Fingerprint recomputed from the supplied buffers.

ExclusionRecordMismatch

The recomputed cross-split exclusion record disagrees with the attested one.

Fields

expected: String

Exclusion record digest recorded in the attestation.

got: String

Exclusion record digest recomputed from the supplied buffers.

SelfPair

A pair was requested whose two endpoints are the same selected ordinal.

D-12: unreachable through the sampler, because CanonicalPair::new is the sole constructor and it rejects equal endpoints. It IS reachable through the untrusted pair-ingest boundary, which is why the variant exists.

Fields

id: u64

The selected-example ordinal that appeared on both sides.

NoPairCapacity

The layout admits no pairs of either kind.

Fields

positive_capacity: u64

Number of distinct same-class unordered pairs available.

negative_capacity: u64

Number of distinct cross-class unordered pairs available.

ZeroBudget

An effective pair budget of zero was resolved or requested.

ZeroHardCap

A pair hard cap of zero was configured.

Distinct from Self::ZeroBudget: a zero cap means no budget can ever be satisfied, which is a configuration defect rather than a request defect.

BudgetExceedsHardCap

An explicit budget above the configured hard cap.

This FAILS rather than silently clamping: the cap exists for DoS control, and a user who typed a larger number deserves to be told it was refused, not to receive a quietly different dataset (budget_resolution).

Fields

budget: u64

Budget the caller requested.

hard_cap: u64

Configured hard cap.

BudgetExceedsCapacity

A budget exceeding the available UNIQUE pair capacity (D-11).

Reserved for the unique-capacity check. The oversampling strategy draws with replacement, so budget > capacity is not an error there.

Fields

budget: u64

Budget the caller requested.

capacity: u64

Unique pair capacity available for the strategy.

OrdinalOutOfRange

A pair was requested at an ordinal at or beyond the resolved budget.

Fields

ordinal: u64

The requested draw ordinal.

budget: u64

The resolved effective budget.

PairTargetMismatch

A replayed pair record’s target disagrees with its endpoints’ classes.

The 1.0/0.0 target is DERIVED from endpoint classes at emission and is never accepted from caller input; this variant is how that is enforced for bytes that claim otherwise.

Fields

lo: String

Lower canonical endpoint identifier.

hi: String

Upper canonical endpoint identifier.

declared_target: f32

Target the untrusted record carried.

derived_target: f32

Target derived from the endpoints’ classes.

UnsupportedSchemaVersion

A serialized artifact declares a schema version this build does not support.

Fields

field: String

Which artifact or field carried the version (selection, attestation, …).

got: u32

Version read from the artifact.

supported: u32

Version this build implements.

UnsupportedNormalizationVersion

An artifact was produced under a content-normalization pipeline this build does not implement.

Distinct from Self::UnsupportedSchemaVersion because the normalization version is a STRING tag rather than an integer, and because it changes what the exclusion record MEANS rather than what the artifact’s fields are. Silently accepting a foreign tag would let an exclusion record computed under different collapsing rules be replayed as if it had been computed under these ones (D-17: the normalization is contracted and versioned so it cannot drift).

Fields

got: String

Tag read from the artifact.

supported: &'static str

Tag this build implements.

UnsupportedPolicyVersion

A versioned policy enum value this build does not implement.

Fields

policy: String

Which policy (singleton, degenerate, …).

got: u32

Version read from the artifact.

supported: u32

Version this build implements.

UnsupportedAlgorithmVersion

A sampling-algorithm version this build does not implement.

Separate from Self::UnsupportedPolicyVersion because changing the algorithm changes pair IDENTITIES, whereas changing a policy changes which pairs are legal.

Fields

got: u32

Version read from the artifact.

supported: u32

Version this build implements.

ArithmeticOverflow

A capacity or budget computation overflowed.

Every step of the closed-form capacity math uses checked arithmetic, so a large class layout produces this typed error instead of a wrapped, plausible-looking capacity that would then silently under-sample.

Fields

operation: String

The operation that overflowed (positive_capacity, default_budget, …).

Serialization

Canonical serialization or deserialization of an artifact failed.

Fields

context: String

What was being (de)serialized.

detail: String

The underlying serializer message.

Io

A caller-supplied sink or source failed.

The crate performs NO filesystem or network access (D-04). This variant exists only so dump_pairs<W: Write> can surface the caller’s own writer failure as a typed error rather than swallowing it.

Fields

context: String

What was being written or read.

detail: String

The underlying std::io::Error message.

Trait Implementations

impl Clone for ContrastiveDataError

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ContrastiveDataError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ContrastiveDataError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for ContrastiveDataError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl PartialEq for ContrastiveDataError

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ContrastiveDataError