@packvium/engine 0.1.3 → 1.1.0

package/README.md

@@ -3,6 +3,9 @@
 Deterministic 3D cartonization for Node.js. It uses the optional native engine when
 available and automatically falls back to the bundled JavaScript implementation.
 
+Full documentation, the constraint reference and benchmarks live at
+[packvium.com](https://packvium.com).
+
 ## Install
 
 ```bash
@@ -100,6 +103,10 @@ and execute without a project around it.
 | File | What it shows |
 | --- | --- |
 | [`basic.mjs`](examples/basic.mjs) | Pack an order, read placements, and see why an item was refused. |
+| [`objectives.mjs`](examples/objectives.mjs) | All six objectives on scenes where they genuinely disagree — the same scores the Python, PHP and Rust engines print for the same request. |
+| [`shapes.mjs`](examples/shapes.mjs) | Items that are not their box: complementary wedges sharing one crate as `convex_hull`, and a cushion that compresses under load until the crush limit refuses it. |
+| [`constraints.mjs`](examples/constraints.mjs) | Stacking caps, incompatible tags and atomic groups — each shown with and without the rule, plus how to read the structured refusal. |
+| [`units.mjs`](examples/units.mjs) | Why lengths travel as strings: fractional inches kept exact, one tick deciding a fit, and the point where a JavaScript number stops being exact and a quote is refused rather than rounded. |
 | [`commerce.mjs`](examples/commerce.mjs) | Rate a shipment, apply an eligibility rule, and pin a catalog version. |
 
 ```bash
@@ -133,7 +140,7 @@ Documentation, the constraint reference and the benchmarks are at
 | --- | --- | --- |
 | Python — [`packvium`](https://pypi.org/project/packvium/) | `pip install packvium` | [packvium-python](https://github.com/toxakara/packvium-python) |
 | PHP — [`packvium/packvium`](https://packagist.org/packages/packvium/packvium) | `composer require packvium/packvium` | [packvium-php](https://github.com/toxakara/packvium-php) |
-| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "0.1"` | [packvium-rust](https://github.com/toxakara/packvium-rust) |
+| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.0"` | [packvium-rust](https://github.com/toxakara/packvium-rust) |
 | Node.js — [`@packvium/engine`](https://www.npmjs.com/package/@packvium/engine) | `npm install @packvium/engine` | [packvium-node](https://github.com/toxakara/packvium-node) |
 | Browser / WebAssembly — [`@packvium/browser`](https://www.npmjs.com/package/@packvium/browser) | `npm install @packvium/browser` | [packvium-wasm](https://github.com/toxakara/packvium-wasm) |
 | PHP FFI bridge — [`packvium/native-bridge`](https://packagist.org/packages/packvium/native-bridge) | `composer require packvium/native-bridge` | [packvium-php-bridge](https://github.com/toxakara/packvium-php-bridge) |

package/SECURITY.md

@@ -2,8 +2,8 @@
 
 ## Supported versions
 
-Only the latest `0.1.x` release receives fixes. This is an early release; there is no
-long-term support branch yet.
+Only the latest `1.x` release receives fixes. The `0.1.x` line is superseded by `1.0.0`
+and receives none. There is no long-term support branch for older majors.
 
 ## Reporting a vulnerability
 

package/contact-graph.js

@@ -6,45 +6,106 @@
  * representation can avoid. The exact overlap function remains authoritative.
  * This module is package-internal: package.json exports only the root entry point.
  */
-export function buildContactGraph(boxes, overlapXY) {
-  const supporters = boxes.map(() => []);
-  const children = boxes.map(() => []);
-  if (boxes.length === 0) return { supporters, children, candidateChecks: 0 };
-
-  const cell = Math.max(1, ...boxes.map(box => Math.max(box.d[0], box.d[1])));
-  const byTop = new Map();
-  const levels = new Map();
-  const cells = box => {
-    const x1 = Math.floor(box.x / cell);
-    const x2 = Math.floor((box.x + box.d[0] - 1) / cell);
-    const y1 = Math.floor(box.y / cell);
-    const y2 = Math.floor((box.y + box.d[1] - 1) / cell);
-    return [...new Set([`${x1}:${y1}`, `${x2}:${y1}`, `${x1}:${y2}`, `${x2}:${y2}`])];
-  };
 
+/**
+ * The at-most-four cells `box` occupies.
+ *
+ * `cell` must be at least as large as the largest footprint dimension of every box
+ * hashed into the index or queried against it -- not just the ones being indexed. Only
+ * then is a box guaranteed to span no more than a 2x2 block, which is what makes two
+ * overlapping boxes always share a cell. Sizing it from the indexed boxes alone would be
+ * exactly wrong: a larger querying box could step over cells in the middle of its own
+ * footprint and silently miss a real overlap.
+ */
+function cellsOf(box, cell) {
+  const x1 = Math.floor(box.x / cell);
+  const x2 = Math.floor((box.x + box.d[0] - 1) / cell);
+  const y1 = Math.floor(box.y / cell);
+  const y2 = Math.floor((box.y + box.d[1] - 1) / cell);
+  return [...new Set([`${x1}:${y1}`, `${x2}:${y1}`, `${x1}:${y2}`, `${x2}:${y2}`])];
+}
+
+function bucketsByPlane(boxes, plane) {
+  const byPlane = new Map();
   boxes.forEach((box, index) => {
-    const top = box.z + box.d[2];
-    if (!byTop.has(top)) byTop.set(top, []);
-    byTop.get(top).push(index);
+    const key = plane(box);
+    if (!byPlane.has(key)) byPlane.set(key, []);
+    byPlane.get(key).push(index);
   });
+  return byPlane;
+}
+
+const topOf = box => box.z + box.d[2];
+const bottomOf = box => box.z;
 
+function levelIndex(boxes, indices, cell) {
+  const level = new Map();
+  for (const index of indices) {
+    for (const key of cellsOf(boxes[index], cell)) {
+      if (!level.has(key)) level.set(key, []);
+      level.get(key).push(index);
+    }
+  }
+  return level;
+}
+
+/**
+ * Every box in `buckets` on `plane` that really overlaps `box`, ascending by index.
+ *
+ * Ascending order is contract, not presentation: `topLoads` splits a conserved integer
+ * across the supporter list and hands the rounding remainder to whichever edge is last.
+ */
+function overlapsOnPlane(graph, buckets, cache, plane, box, overlapXY) {
+  const indices = buckets.get(plane);
+  if (!indices) return [];
+  let level = cache.get(plane);
+  if (level == null) {
+    level = levelIndex(graph.boxes, indices, graph.cell);
+    cache.set(plane, level);
+  }
+  const nearby = new Set();
+  for (const key of cellsOf(box, graph.cell)) {
+    for (const index of level.get(key) ?? []) nearby.add(index);
+  }
+  const found = [];
+  for (const other of [...nearby].sort((left, right) => left - right)) {
+    const area = overlapXY(graph.boxes[other], box);
+    if (area > 0) found.push([other, area]);
+  }
+  return found;
+}
+
+/**
+ * `cellHint` is an upper bound on the footprint of any box that may later be appended
+ * with `appendContactBox`.
+ *
+ * Without it the cell is sized from the boxes present now, and appending anything wider
+ * has to fall back to a full rebuild -- correct, but it defeats the point, because in a
+ * search the base is what is already placed and the candidate is a *new* item that may
+ * well be the widest in the request. A caller that knows the item set passes its widest
+ * footprint once and the delta path then always applies. Too large a hint only makes
+ * each bucket coarser; too small a one cannot give a wrong answer, because the fallback
+ * covers it.
+ */
+export function buildContactGraph(boxes, overlapXY, cellHint = 1) {
+  const supporters = boxes.map(() => []);
+  const children = boxes.map(() => []);
+  const cell = Math.max(1, cellHint, ...boxes.map(box => Math.max(box.d[0], box.d[1])));
+  const byTop = bucketsByPlane(boxes, topOf);
+  const byBottom = bucketsByPlane(boxes, bottomOf);
+  const topLevels = new Map();
   let candidateChecks = 0;
+
   boxes.forEach((upper, upperIndex) => {
     const candidates = byTop.get(upper.z);
     if (!candidates) return;
-    let level = levels.get(upper.z);
+    let level = topLevels.get(upper.z);
     if (level == null) {
-      level = new Map();
-      for (const index of candidates) {
-        for (const key of cells(boxes[index])) {
-          if (!level.has(key)) level.set(key, []);
-          level.get(key).push(index);
-        }
-      }
-      levels.set(upper.z, level);
+      level = levelIndex(boxes, candidates, cell);
+      topLevels.set(upper.z, level);
     }
     const nearby = new Set();
-    for (const key of cells(upper)) {
+    for (const key of cellsOf(upper, cell)) {
       for (const index of level.get(key) ?? []) nearby.add(index);
     }
     for (const lowerIndex of [...nearby].sort((left, right) => left - right)) {
@@ -57,5 +118,58 @@ export function buildContactGraph(boxes, overlapXY) {
       }
     }
   });
-  return { supporters, children, candidateChecks };
+  // The downward-facing indexes stay empty here: only an append queries them, and a graph
+  // built once and read once would otherwise pay for an index nothing looks at.
+  return { supporters, children, candidateChecks, boxes, cell, byTop, byBottom, topLevels,
+           bottomLevels: new Map() };
+}
+
+/**
+ * `graph` plus one more box, appended at the next index.
+ *
+ * Adding a box cannot create or destroy contact between two boxes already in the graph:
+ * contact is a pairwise geometric predicate over two boxes and nothing else. That is the
+ * whole reason a delta is sound, and it is why only the new box's own two planes are
+ * queried instead of every box being re-examined.
+ *
+ * The result is required to be identical to `buildContactGraph([...boxes, box])`, not
+ * merely equivalent -- see `overlapsOnPlane` on why edge order is contract. The new box
+ * takes the highest index, so appending it to an existing list keeps that list ascending.
+ *
+ * `graph` is not modified: the returned graph shares every edge list the append did not
+ * touch, and copies the two or three it did.
+ */
+export function appendContactBox(graph, box, overlapXY) {
+  const index = graph.boxes.length;
+  const footprint = Math.max(box.d[0], box.d[1]);
+  if (footprint > graph.cell) {
+    // The broad phase is only correct while its cell covers every box hashed into it or
+    // queried against it, so this is a correctness fallback, not an optimisation choice.
+    return buildContactGraph([...graph.boxes, box], overlapXY, footprint);
+  }
+
+  const below = overlapsOnPlane(graph, graph.byTop, graph.topLevels, box.z, box, overlapXY);
+  const above = overlapsOnPlane(graph, graph.byBottom, graph.bottomLevels, topOf(box), box, overlapXY);
+
+  const supporters = graph.supporters.slice();
+  const children = graph.children.slice();
+  supporters.push(below.map(([lower, area]) => [lower, area]));
+  children.push(above.map(([upper]) => upper));
+  for (const [lower] of below) children[lower] = [...children[lower], index];
+  for (const [upper, area] of above) supporters[upper] = [...supporters[upper], [index, area]];
+
+  // One box joins exactly two planes, so only those two buckets change, and only the two
+  // level indexes describing them are invalidated. A level index is never mutated after
+  // it is built, so every other one is shared with the base rather than rebuilt.
+  const byTop = new Map(graph.byTop);
+  byTop.set(topOf(box), [...(byTop.get(topOf(box)) ?? []), index]);
+  const byBottom = new Map(graph.byBottom);
+  byBottom.set(box.z, [...(byBottom.get(box.z) ?? []), index]);
+  const topLevels = new Map(graph.topLevels);
+  topLevels.delete(topOf(box));
+  const bottomLevels = new Map(graph.bottomLevels);
+  bottomLevels.delete(box.z);
+
+  return { supporters, children, candidateChecks: graph.candidateChecks,
+           boxes: [...graph.boxes, box], cell: graph.cell, byTop, byBottom, topLevels, bottomLevels };
 }

package/examples/constraints.mjs

@@ -0,0 +1,97 @@
+/**
+ * Constraints: how to say "this may not go there", and how to read the refusal.
+ *
+ * Run it:
+ *
+ *     node examples/constraints.mjs
+ *
+ * Most real packing rules are refusals — this side up, nothing on top of that, keep the
+ * chemicals away from the food — and the useful half of the answer is often the item that
+ * did *not* fit and the reason it did not.
+ *
+ * Every rule below is a field on an item or a container. None of them needs a custom
+ * class, none of them changes how you call `pack`, and every one is part of the shared
+ * JSON contract, so the same request answers the same way from the Python, PHP and Rust
+ * engines.
+ */
+
+import { pack } from '../index.js';
+
+const MM = { units: { length: 'mm' } };
+
+/**
+ * Pack one variant and print what it cost.
+ *
+ * Both numbers matter. A constraint only sometimes shows up as a refusal; more often the
+ * solver satisfies it by opening another container, which costs money and is the outcome
+ * you actually wanted to see coming.
+ */
+const solve = (label, items, containers) => {
+  const result = pack({ ...MM, items, containers });
+  const placed = result.containers.reduce((n, c) => n + c.placements.length, 0);
+  console.log(
+    `  ${label.padEnd(20)} ${result.containers.length} container(s), ` +
+    `${placed} placed, ${result.unpacked_items.length} refused`,
+  );
+  for (const unpacked of result.unpacked_items) {
+    console.log(`      ${unpacked.item_id.padEnd(12)} ${unpacked.reason}`);
+  }
+};
+
+const shelf = [{ id: 'shelf', inner_dimensions: { length: '800', width: '400', height: '500' } }];
+
+// ------------------------------------------------------------------ a plain refusal
+//
+// The ladder is longer than the shelf's longest inner edge in every orientation, so no
+// solver can place it. The reason code says exactly that, and it is a fact about the
+// request rather than a solver failure — which is why it is safe to show a customer.
+
+console.log('a refusal that no solver can avoid');
+solve('ladder + books',
+  [{ id: 'ladder', quantity: 1, dimensions: { length: '1800', width: '300', height: '100' } },
+   { id: 'book', quantity: 4, dimensions: { length: '210', width: '140', height: '30' } }],
+  shelf);
+
+// --------------------------------------------------------------- one rule at a time
+//
+// Each rule below is shown twice: same items, same container, once without it and once
+// with it. A constraint you cannot watch change the answer is one the reader has to take
+// on faith, and the pair makes the rule — rather than the geometry — provably the cause.
+
+const tin = { length: '150', width: '150', height: '120' };
+const column = [{ id: 'column', inner_dimensions: { length: '160', width: '160', height: '600' } }];
+
+// `max_stacked_items` caps how many units may sit above one item — a pallet-pattern rule
+// ("three high, no more"), not a weight limit. The column is one tin wide, so height is
+// the only way to fit more, and the second column is the price of the cap.
+console.log('\nmax_stacked_items — five tins fit one column; three-high needs two');
+solve('without', [{ id: 'tin', quantity: 5, dimensions: tin, weight: { value: '800', unit: 'g' } }], column);
+solve('with', [{ id: 'tin', quantity: 5, dimensions: tin, weight: { value: '800', unit: 'g' }, max_stacked_items: 3 }], column);
+
+// Tags are how two items refuse each other. `incompatible_tags` is checked both ways, so
+// tagging one side is enough. Nothing asked for a second shelf — the tag did.
+const bleach = (tags) => ({ id: 'bleach', quantity: 2,
+  dimensions: { length: '120', width: '120', height: '300' }, weight: { value: '2', unit: 'kg' }, ...tags });
+const flour = { id: 'flour', quantity: 3,
+  dimensions: { length: '200', width: '150', height: '100' }, weight: { value: '1500', unit: 'g' }, tags: ['food'] };
+
+console.log('\nincompatible_tags — hazmat and food cannot share a container');
+solve('without', [bleach({}), flour], shelf);
+solve('with', [bleach({ tags: ['hazmat'], incompatible_tags: ['food'] }), flour], shelf);
+
+// `group` is atomic: every member ships in one container or none of them does. The third
+// part is deliberately too long for the shelf, so it takes the other two down with it
+// rather than shipping two thirds of an assembly nobody can use.
+const parts = [{ length: '200', width: '200', height: '100' },
+               { length: '200', width: '200', height: '100' },
+               { length: '900', width: '100', height: '100' }];
+const kit = (group) => parts.map((dimensions, n) => ({
+  id: `kit-${n + 1}`, quantity: 1, dimensions, weight: { value: '2', unit: 'kg' }, ...group }));
+
+console.log('\ngroup — one member cannot be placed, so none of them is');
+solve('without', kit({}), shelf);
+solve('with', kit({ group: 'assembly' }), shelf);
+
+// Every reason code above is structured, not prose: `reason` is a stable identifier and
+// `proof` carries the observations behind it. Render your own wording from the code —
+// the strings here are the contract's, not a message meant for your customer.

package/examples/shapes.mjs

@@ -0,0 +1,155 @@
+/**
+ * Shapes: when an item is not its box.
+ *
+ * Run it:
+ *
+ *     node examples/shapes.mjs
+ *
+ * Every other example treats an item as the box it declares. That is the default and it
+ * is right for almost everything, because a carton *is* a cuboid. Two kinds of goods are
+ * not: a moulded or tapered part that leaves a usable void beside it, and a soft one that
+ * gives way under whatever is stacked on it.
+ *
+ * `shape_type` narrows the box in one direction each -- `convex_hull` in space,
+ * `compressible` in height under load -- and neither is ever inferred. An engine that
+ * quietly packed a hull as its bounding box would return a plan that validates and does
+ * not physically fit, so the value must be asked for.
+ *
+ * These fields are part of the shared request contract, so the same document runs
+ * unchanged against the Python, PHP and Rust engines. It does not follow that all four
+ * print the same numbers -- see the note on the compressible section below, which is the
+ * more useful half of the lesson.
+ */
+
+import { pack } from '../index.js';
+
+const MM = { units: { length: 'mm' } };
+const crate = (length, width, height) => [
+  { id: 'crate', inner_dimensions: { length, width, height } },
+];
+
+/** Run one request and print only what the shape changed: containers and refusals. */
+const summarise = (label, request) => {
+  const result = pack({ ...MM, ...request });
+  const placed = result.containers.reduce((n, c) => n + c.placements.length, 0);
+  console.log(
+    `  ${label.padEnd(22)} ${result.status.padEnd(10)} ` +
+    `${result.containers.length} container(s), ${placed} placed, ` +
+    `${result.unpacked_items.length} refused`,
+  );
+};
+
+// ------------------------------------------------------------------ convex_hull
+//
+// Two triangular prisms, each cut from the same 100 mm cube along the diagonal. Their
+// bounding boxes are identical and fill the crate on their own, so as cuboids the second
+// one has nowhere to go. As hulls they are complementary halves and share the crate
+// exactly -- the collision test is an exact integer separating-axis test on the vertices,
+// not a box overlap.
+//
+// The hull is given in the item's own coordinates, in the request's length unit, and must
+// fit inside the declared dimensions. It is not a replacement for them: the box still
+// bounds the item, the hull only says how much of that box is solid.
+
+const LOWER_WEDGE = [
+  { x: '0', y: '0', z: '0' }, { x: '100', y: '0', z: '0' },
+  { x: '0', y: '100', z: '0' }, { x: '0', y: '0', z: '100' },
+  { x: '100', y: '0', z: '100' }, { x: '0', y: '100', z: '100' },
+];
+const UPPER_WEDGE = [
+  { x: '100', y: '100', z: '0' }, { x: '100', y: '0', z: '0' },
+  { x: '0', y: '100', z: '0' }, { x: '100', y: '100', z: '100' },
+  { x: '100', y: '0', z: '100' }, { x: '0', y: '100', z: '100' },
+];
+
+const wedge = (id, vertices) => ({
+  id,
+  quantity: 1,
+  dimensions: { length: '100', width: '100', height: '100' },
+  weight: { value: '1', unit: 'kg' },
+  ...(vertices ? { shape_type: 'convex_hull', hull_vertices: vertices } : {}),
+});
+
+console.log('convex_hull -- two complementary wedges cut from one cube');
+summarise('as cuboids', {
+  items: [wedge('wedge-lower', null), wedge('wedge-upper', null)],
+  containers: crate('100', '100', '100'),
+});
+summarise('as hulls', {
+  items: [wedge('wedge-lower', LOWER_WEDGE), wedge('wedge-upper', UPPER_WEDGE)],
+  containers: crate('100', '100', '100'),
+});
+
+// One crate instead of two, for the same goods and the same crate. Nothing about the
+// request changed except the claim that the items are wedges rather than blocks.
+
+// ----------------------------------------------------------------- compressible
+//
+// `compression_ratio` is the fraction of its own height an item may lose when something
+// rests on it -- 0.25 means it can give up a quarter. The mass above it is what decides
+// how much it actually gives, so the occupied height of a compressible item is not a
+// property of the item alone; it depends on what the solver put on top.
+//
+// `max_compression_pressure_kpa` is the other half of the same field. Past that pressure
+// the item is not compressed further, it is crushed, and the load is refused instead.
+//
+// Note `must_be_on_floor` on the cushion. Without it the solver is free to put the brick
+// underneath, nothing bears on the cushion, and the feature never engages -- which is the
+// honest reason the rule is here and not an incidental detail of the example.
+
+const cushion = (crushKpa) => ({
+  id: 'cushion',
+  quantity: 1,
+  dimensions: { length: '100', width: '100', height: '100' },
+  weight: { value: '2', unit: 'kg' },
+  must_be_on_floor: true,
+  shape_type: 'compressible',
+  compression_ratio: 0.25,
+  max_compression_pressure_kpa: crushKpa,
+});
+
+const brick = (kilograms) => ({
+  id: 'brick',
+  quantity: 1,
+  dimensions: { length: '100', width: '100', height: '100' },
+  weight: { value: String(kilograms), unit: 'kg' },
+});
+
+/** One crate, one cushion, one brick -- only the brick's mass changes. */
+const load = (label, kilograms) => {
+  const result = pack({
+    ...MM,
+    items: [cushion(100), brick(kilograms)],
+    containers: crate('100', '100', '200'),
+  });
+  console.log(
+    `  ${label.padEnd(22)} ${result.containers.length} container(s), ` +
+    `unused volume ${result.score[3]} ppm`,
+  );
+};
+
+// The crate is 100x100x200 and the two items are 100 mm cubes, so rigidly they fill it
+// exactly and nothing is unused. At 102 kg the brick crosses 100 kPa over the cushion's
+// 0.01 m^2 face: the stack is refused, the brick opens a second crate, and half of each
+// crate is empty.
+//
+// At 101 kg this engine also opens two crates -- and the Python, PHP and Rust engines
+// return one, with the cushion compressed. Both answers are valid: every item is placed,
+// no rule is broken, and an independent validator accepts each. This one is simply worse,
+// and it is recorded as such in the suite's quality budget rather than left to be
+// discovered here.
+//
+// That is the guarantee, stated exactly. What the shared contract fixes is the request
+// shape, the validity rules and the objective vector -- not which of several valid
+// arrangements a given engine finds. An engine may return a worse-scoring valid packing;
+// none may return an invalid one. If you need the best answer these fields can give,
+// solve on the Rust or Python engine and treat the JavaScript fallback as the portable
+// one.
+console.log('\ncompressible -- a cushion that yields to the load above it');
+load('brick 101 kg', 101);
+load('brick 102 kg', 102);
+
+// Both shapes are refused rather than approximated wherever an engine cannot honour them
+// exactly -- a hull on a route, a hull under a configured clearance, a compressible item
+// with `nesting_height`. A wrong answer that validates is worse than a refusal that does
+// not, which is the whole reason these are opt-in.

package/examples/units.mjs

@@ -0,0 +1,115 @@
+/**
+ * Units and numbers: why nothing here is a JavaScript number until you make it one.
+ *
+ * Run it:
+ *
+ *     node examples/units.mjs
+ *
+ * Every length and weight in the contract travels as a **decimal string**, and every
+ * length in a result is an exact integer count of ticks — one tick is 1/16000 mm. That is
+ * not ceremony. `0.1 + 0.2 !== 0.3` is true in this language, and a packing engine that
+ * decides a fit by a hair has no room for a representation that rounds.
+ *
+ * This example is the JavaScript one on purpose. Of the four engines, this is the one
+ * whose native number type stops being exact partway through the range the contract
+ * allows, and the last section shows exactly where that boundary is and what happens when
+ * you cross it.
+ */
+
+import { pack, commerce, CommerceInputError } from '../index.js';
+
+// ------------------------------------------------------------- fractions survive intact
+//
+// Imperial sizes arrive as fractions far more often than as decimals, and "12 3/8" is an
+// exact quantity while 12.375 is a float that happens to be exact and 8.1 is one that is
+// not. Send the fraction; the engine converts once, exactly, into integer ticks.
+
+const inches = pack({
+  units: { length: 'in' },
+  items: [{ id: 'plank', quantity: 2, dimensions: { length: '12 3/8', width: '8 1/2', height: '3/4' } }],
+  containers: [{ id: 'crate', inner_dimensions: { length: '24', width: '24', height: '24' } }],
+});
+
+console.log('fractional inches');
+console.log(`  status: ${inches.status}`);
+for (const placement of inches.containers[0].placements) {
+  const { x, y, z } = placement.position;
+  console.log(`  ${placement.item_id.padEnd(9)} at ticks (${x.ticks}, ${y.ticks}, ${z.ticks})`
+    + `  = (${x.value}, ${y.value}, ${z.value}) ${x.unit}`);
+}
+
+// Both forms come back: `ticks` is the exact integer the engine reasoned with, `value` is
+// the same quantity rendered in the unit you asked for. Compare `ticks` when you need to
+// know whether two things are the same; `value` is for showing a human.
+
+// ------------------------------------------------------------------ one tick decides it
+//
+// A container exactly one tick shorter than the item refuses it. There is no tolerance to
+// tune, because a tolerance is a decision about someone else's warehouse.
+
+const TICKS_PER_MM = 16000;
+const fit = (containerMm) => {
+  const result = pack({
+    units: { length: 'mm' },
+    items: [{ id: 'rod', quantity: 1, dimensions: { length: '100', width: '10', height: '10' } }],
+    containers: [{ id: 'tube', inner_dimensions: { length: containerMm, width: '10', height: '10' } }],
+  });
+  const refused = result.unpacked_items[0];
+  return refused ? `refused: ${refused.reason}` : 'placed';
+};
+
+console.log('\none tick decides it');
+console.log(`  container 100 mm exactly     -> ${fit('100')}`);
+console.log(`  container one tick shorter   -> ${fit(String((100 * TICKS_PER_MM - 1) / TICKS_PER_MM))}`);
+
+// ------------------------------------------------- where JavaScript's numbers give out
+//
+// Lengths never reach the boundary in practice. Money does: a quote is minor currency
+// units, and a large enough shipment at a large enough rate multiplies past `2^53 - 1`,
+// after which a JavaScript number is no longer exact and `n + 1 === n` becomes possible.
+//
+// The engine refuses rather than returning a rounded price. A wrong number that looks
+// right is the worst outcome available here — it would be invoiced.
+
+const document = {
+  tariffs: [{
+    carrier_id: 'acme',
+    service_id: 'ground',
+    versions: [{
+      effective_at: 0,
+      dimensional_weight_divisor: 1,
+      cost_per_dimensional_kg_minor: { 'zone-a': 1_000_000 },
+      minimum_charge_minor: 0,
+      fuel_surcharge_permille: 0,
+      accessorials: [],
+    }],
+  }],
+};
+
+const quote = (volumeMm3) => commerce.quote(document, {
+  carrier_id: 'acme', service_id: 'ground', zone: 'zone-a',
+  as_of: 0, actual_weight_g: 0, volume_mm3: volumeMm3,
+});
+
+console.log('\nwhere JavaScript stops being exact');
+console.log(`  Number.MAX_SAFE_INTEGER = ${Number.MAX_SAFE_INTEGER}  (2^53 - 1)`);
+console.log(`  and past it: 2^53 + 1 === 2^53 is ${2 ** 53 + 1 === 2 ** 53}`);
+
+for (const volume of [10 ** 12, 10 ** 15]) {
+  try {
+    const answer = quote(volume);
+    console.log(`  volume ${String(volume).padEnd(16)} -> ${answer.quote.total_minor} minor units`);
+  } catch (error) {
+    if (!(error instanceof CommerceInputError)) throw error;
+    console.log(`  volume ${String(volume).padEnd(16)} -> refused: ${error.message}`);
+  }
+}
+
+// The refusal is the contract working, not the binding failing: an answer this engine
+// cannot represent exactly is one it declines to give.
+//
+// The check lives here and nowhere else — `commerce-model.js` is the only file in the
+// suite that carries it — because `2^53` is a property of this language's number type
+// rather than of the contract. What the Python and PHP engines return for the same
+// request is their own business and is not asserted here; if you need a number this large
+// to survive, do not read it out of a JavaScript `Number`.