@packvium/engine 0.1.2 → 1.0.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,8 @@ 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. |
 | [`commerce.mjs`](examples/commerce.mjs) | Rate a shipment, apply an eligibility rule, and pin a catalog version. |
 
 ```bash
@@ -126,11 +131,14 @@ One request and result contract, implemented independently in four engines (Rust
 Python, PHP, JavaScript) and held to identical placements on a shared fixture set.
 Pick the package for your stack; mixing them in one system is safe.
 
+Documentation, the constraint reference and the benchmarks are at
+[packvium.com](https://packvium.com).
+
 | Package | Install | Source |
 | --- | --- | --- |
 | 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/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.