DOCS / EXPLANATION

Building a deterministic packing engine, four times

Why this engine is four independent implementations held to one conformance corpus, not one core with four bindings.

Docs for Packvium 1.11.x · contract stable since 1.0

01The problem: a box that fits on paper and not in the truck#

A "does it fit" answer built from a volume total treats every item as a number, not a shape. Two items that fit by volume can still fail to arrange inside the same box, and a container with room to spare can still be the wrong one for cargo that a compatibility rule keeps apart from what is already inside it. Cartonization, pallet loading, container loading and warehouse storage are the same underlying problem asked four different ways: exact geometry, real constraints, and a search that either finds an arrangement or names the one item with nowhere to go.

02Why floating point is the wrong arithmetic for this decision#

An engine that measures in floating-point millimetres can disagree with itself between two builds, two platforms, or two runs of the same request - not because the logic changed, but because the rounding did. That is not an acceptable property for a decision that ends up on a shipping label or a load plan. Every length here is instead carried as an exact integer tick - 1/16000 of a millimetre - from the moment it is parsed: a value given in millimetres, inches or any other declared unit converts once, on the way in, and every comparison after that is exact integer arithmetic. A request that mixes inches and millimetres in the same document is exact, not approximated to a shared precision.

03Determinism is a boundary, not a setting#

A run's search is bounded by an explicit deadline, an effort budget counted in solver operations rather than wall-clock time, and a seed. Nothing inside the engine reaches for a network call, a system clock, or a retry that could make two runs of the same request diverge. That is what makes "run it again and compare" a meaningful sentence instead of a coin flip.

04One request document, four independent implementations#

The Python, PHP, Rust and JavaScript engines are not four bindings around one core - they are four independent implementations of the same request and result contract, held to one conformance corpus rather than to each other's source. Python and PHP are held to byte-identical canonical results on every fixture; the Rust core and the JavaScript fallback run their own searches and are held to independent validity and a committed per-fixture objective floor instead, since two arrangements can both be correct and still not be the same arrangement. Closing that remaining gap is ongoing work, not a footnote written around it.

05A validator that shares no code with the solver#

A solver checking its own placements against its own bookkeeping proves that the code agrees with itself, not that the placements are legal. Every result here is independently recomputed by a validator built from none of the solver's code: the objective, and every constraint that affected it, computed fresh from the placements the solver actually returned. A visualisation of a result and evidence that the result is correct are two different claims, and only the second one is made here.

06How the benchmark numbers are allowed to be published#

No performance claim runs here without a pinned dataset, named competitor versions and the raw artifacts behind it. Runtime is recorded per run but is deliberately not a ranking axis, because comparing wall-clock time across engines that were not run on identical hardware compares host machines, not algorithms. Volume utilisation and packed fraction are recomputed by the same independent validator from whatever placements an engine actually returned, never taken from that engine's own printed summary. An engine counts as Pareto-optimal when nothing beat it on every axis at once - there is deliberately no blended score, because collapsing two numbers into one hides exactly the tradeoff a reader came to see.

07The tradeoffs this makes on purpose#

Exact integer geometry and independent revalidation cost search speed that a looser floating-point heuristic would not have to pay. A library with no service, no database and no framework to adopt cannot offer the convenience of a hosted API a caller never has to run themselves. And bin packing's own NP-hardness means a large or awkward request is answered best-found within a time budget, not proven optimal, on any runtime that has not paid for a full exact-solver pass. None of these sit behind marketing language - each is a named constraint on its own page, with a field or a status value a caller can check it against.

08What this does not do#

No concave meshes, soft bags or cylinders as items, though a container can be a flat or gusseted mailer: rigid cuboids, plus two shapes a caller opts into per item - a convex hull decided by exact integer geometry, and a compressible item whose height yields under load to a declared crush limit. No optimum claimed beyond a proof: under every objective a result carries the engine's lower bound and its gap to it, and is called optimal only when it reaches that bound. No speed comparison against the other benchmarked engines: one of them only builds for a single platform and runs under emulation on the comparator host, which would rank host machines rather than algorithms. No live carrier rate lookup: tariff data is the caller's own.