01One schema, four engines#
The request schema in the conformance suite is the source of truth. An engine either implements a field or refuses it by name, saying it does not support that field. Reading a request and answering confidently without honouring it is the one behaviour the contract forbids.
02What a capability requires#
A field counts as a capability only when it is in the schema, implemented or explicitly rejected by every engine, exercised by a named fixture, listed in the public field matrix, recomputed by the independent validator and documented. Anything short of that is a prototype.
03Refusals are structured#
Every unpacked item carries a reason, human-readable details and how strongly that reason is backed: proven, measured, inferred, or unknown because a search limit was reached first. A refusal that cannot be explained is treated as a defect.
04A malformed request is refused by name#
Since 1.4.0 a request that no engine may answer is refused before anything is solved, in the same words by every engine: the code invalid_request, a reason from a closed set of nine, and the JSON Pointer of the value refused, as in invalid_request: /items/0/quantity: must be at least 1. Branch on the reason and the field; show the message to a person. Python, PHP and JavaScript raise it as a subclass of the exception they raised before, so existing handlers still catch it; Rust returns it as PackError::InvalidRequest. Since 1.5.0 a configuration key the schema does not declare, such as profile for solver_profile, is refused the same way, as not_allowed at /configuration/profile; earlier engines ignored it and solved on defaults. A valid request that does not fit completely is not an error: what was left out, and why, is in the result.
import { InvalidRequestError, pack } from '@packvium/engine';
try {
const result = pack(request);
} catch (error) {
if (!(error instanceof InvalidRequestError)) throw error;
error.code; // 'invalid_request'
error.reason; // 'below_minimum'
error.field; // '/items/0/quantity' -- a JSON Pointer into your request
error.message; // 'invalid_request: /items/0/quantity: must be at least 1'
}Reference tables
Read from the same constants the engine, the playground and the validator use, so this page cannot drift from the code.
Rejection reasons
no_feasible_placementNo free space left that it fits intono_compatible_container_dimensionsToo large for every container on offerno_eligible_containerNo container passes its eligibility checksrotation_restrictedNo permitted rotation fitspayload_exceededWould push the container past its payload limitaxle_overloadedWould overload an axle wherever it standsinsufficient_supportIt would fit, but only resting on too little supportgroup_cannot_fit_togetherIts group cannot be kept togetherpolicy_ruleA packing rule forbids itcontainer_inventory_exhaustedIt needs another container and the inventory ran outeffort_limitThe search budget ran out firsttime_limitThe time limit expired before it was reachedsearch_exhaustedEvery arrangement was tried and none workedexact_search_incompleteThe exact search ended before it had an answer
Proof levels
provenProven: The request alone rules it out - a size, payload, rotation, container-eligibility or policy bound it breaks, however far the search got.observedMeasured: The search tried and found no placement. That is what it saw, not a proof that none exists.inferredInferred: Follows from the solver's state or a compound rule but has no complete certificate, for example that the declared container inventory ran out.unknown_due_to_limitNot established before the deadline: A deadline or effort limit stopped the search, so no negative conclusion is claimed.
Why a request is refused
missing_fieldA field the request needs is absentwrong_typeA value is the wrong kind, such as text where a number belongsbelow_minimumA number is below the smallest value the field allowsabove_maximumA number is above the largest value the field allowsnegative_measureA length, weight or other measure is negativeinvalid_unitA unit the contract does not recogniseduplicate_idTwo items or two containers share one idnot_allowedA field or value that is not allowed where it appearsinvalid_valueA value the field does not accept