DOCS / REFERENCE

Request and result contract

The public fields, what each status means, and the rule a capability must satisfy before it is one: schema, fixture, validator, docs.

Docs for Packvium 1.11.x · contract stable since 1.0

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 into
  • no_compatible_container_dimensionsToo large for every container on offer
  • no_eligible_containerNo container passes its eligibility checks
  • rotation_restrictedNo permitted rotation fits
  • payload_exceededWould push the container past its payload limit
  • axle_overloadedWould overload an axle wherever it stands
  • insufficient_supportIt would fit, but only resting on too little support
  • group_cannot_fit_togetherIts group cannot be kept together
  • policy_ruleA packing rule forbids it
  • container_inventory_exhaustedIt needs another container and the inventory ran out
  • effort_limitThe search budget ran out first
  • time_limitThe time limit expired before it was reached
  • search_exhaustedEvery arrangement was tried and none worked
  • exact_search_incompleteThe exact search ended before it had an answer

Proof levels

  1. provenProven: The request alone rules it out - a size, payload, rotation, container-eligibility or policy bound it breaks, however far the search got.
  2. observedMeasured: The search tried and found no placement. That is what it saw, not a proof that none exists.
  3. 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.
  4. 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 absent
  • wrong_typeA value is the wrong kind, such as text where a number belongs
  • below_minimumA number is below the smallest value the field allows
  • above_maximumA number is above the largest value the field allows
  • negative_measureA length, weight or other measure is negative
  • invalid_unitA unit the contract does not recognise
  • duplicate_idTwo items or two containers share one id
  • not_allowedA field or value that is not allowed where it appears
  • invalid_valueA value the field does not accept