In the library

The library raises two different kinds of error. A contract error means the call was malformed: mismatched shapes, a negative weight, a criterion paired with a configuration that cannot serve it. A refusal is not that. The arguments are well formed and the computation would run; the library declines because what the call asks it to assert is false in general, and it names the exact counterexample that makes it false.

Each refusal below therefore comes with a fixture: a small table of exact rational scores on which the asserted property demonstrably fails. A reader who doubts a refusal can read the fixture instead of taking the refusal on trust.

The refusals

RefusalRaised onRests onInstead
CE-DS-GLOBAL-GEOMETRY-001

a global profiled optimum can violate its own first-order rule, so profiled labels have no canonical extension

compile_quantizer() on a result fitted under ProfiledDOptimality

Fit a reusable rule directly with fit_quantizer instead of converting a fixed-sample partition

CE-D-VORONOI-CONVERSE-001

looking geometric is strictly weaker than being exchange-stable

compile_quantizer() on a partition whose stability certificate is False

Inspect best_remaining_gain; raise max_scans, or set guard="exchange" on the guarded batch solver

CE-D-UNMERGED-DUPLICATES-001

split duplicate atoms can be vacuously stable while defeating label reproduction

The terminal rule would relabel a training row by more than the gain tolerance

Merge or consistently label coincident score rows; inspect geometry.maximum_violation_gain

CE-DS-MARGINS-RANK-VACUITY-001

The cardinality boundary of OPEN-DS-MARGINS-AT-OPTIMA, and behind it the rank ceiling FI-RANK-CEILING

A profiled fit or partition whose cell count cannot generate nonsingular binned information

Raise n_bins above the score dimension. On an exactly centred sample no sample size helps — this is arithmetic, not a data problem

What each object rests on

Every public object below is listed with the results that justify it. Where the list is empty the object is bookkeeping: it reports or carries what another object established, and adds no claim of its own.

Criteria
ProfiledDOptimality (opens in a new tab)

The log determinant of the Schur complement for the declared parameters of interest. The interest argument is the parameter block; at least one nuisance column must remain

Solver configurations
DExchangeConfig (opens in a new tab)

Exact positive-gain one-point exchange: the closed-form relocation gain on the rank-two update, accepted only on strictly positive exact gains so the search terminates

MahalanobisLloydConfig (opens in a new tab)

Batch reassignment as a proposal, accepted on the exact objective. The guard exists because the unguarded step is not monotone; guard="exchange" hands the labels to the exact engine so the reported state stays compilable

ScalarDPConfig (opens in a new tab)

Exact interval dynamic programming on one score coordinate — the optimal cells are intervals, so the program returns a global optimum rather than a local one

Results and certificates
PartitionResult (opens in a new tab)

A labelling of one fixed sample — the first of the three questions. It deliberately has no predict method, because a finite labelling does not determine its own extension

No result of its own.

PartitionResult.compile_quantizer() (opens in a new tab)

The one exception: an exchange-stable, nonsingular DOptimality result compiles into a Mahalanobis rule. It is bookkeeping, not a second fit

GeometryReport (opens in a new tab)

Measures both sides of the exchange-implies-Voronoi theorem on the terminal state instead of assuming them. guaranteed_violation_gain is the theorem's lower bound; maximum_violation_gain is the exact gain the theorem bounds; maximum_separation_residual checks the leverage inequality, so a positive value indicates numerical trouble rather than a better partition

StabilityReport (opens in a new tab)

One complete exact scan certifying that no single relocation improves a supplied labelling, at a stated gain_tolerance. A labelling certified at one tolerance is not certified at a smaller one

No result of its own.

PartitionCertificate (opens in a new tab)

The outcome of a bounded global search using the singleton-completion ceiling. status is either "optimal" or "budget_exhausted"; the second proves nothing about the incumbent, and incumbent_was_optimal is False whenever it occurs

EfficientScoreBound (opens in a new tab)

The full-data efficient-score ceiling on profiled information, attained for one parameter of interest by the exact interval program. Its labels also serve as a strong initializer

ProfiledGeometryReport (opens in a new tab)

Diagnoses the finite efficient-semimetric gap — the quantity that the profiled case has instead of a geometry theorem

Information reports
InformationReport.arithmetic_mean_retention, and the eigenvalue list (opens in a new tab)

Direction-resolved diagnostics. They are reported separately because optimizing the determinant does not equalize retention across directions — a caution, not a theorem

Sources and score providers
ScoreSample (opens in a new tab)

The scores are supplied directly; provenance is exact and every identity on these pages applies as written

No result of its own.

ratios_from_posteriors (opens in a new tab)

Calibrated classifier posterior odds recover component density ratios when the training priors are known

RatioProvenance, ScoreProvenance (opens in a new tab)

The record of which of the above applies. Estimated ratios never claim exact Fisher semantics, because the retained information is governed by the true score under the estimated rule and no theorem yet bounds the difference

ratio_closure_report (opens in a new tab)

A necessary check that model ratios integrate to one under the reference measure. It is necessary and not sufficient: a small residual never upgrades estimated provenance to exact

No result of its own.