@packvium/engine 0.1.0 → 0.1.2

package/examples/basic.mjs

@@ -0,0 +1,67 @@
+/**
+ * Pack an order, read the placements, and see why anything was refused.
+ *
+ * Run it:
+ *
+ *     node examples/basic.mjs
+ *
+ * `@packvium/engine` takes and returns the same JSON contract every Packvium
+ * implementation speaks, so a request you build here also works against the Python CLI,
+ * the PHP CLI or the Rust core, and comes back with the same answer.
+ *
+ * The package prefers the compiled N-API addon when `@packvium/native` is installed and
+ * falls back to a deterministic JavaScript engine otherwise. You do not choose, and you
+ * do not need to: `backend()` reports which one answered, and both answer the same.
+ */
+
+import { backend, pack, version } from '../index.js';
+
+console.log(`engine ${version()} using the ${backend()} backend\n`);
+
+const request = {
+  items: [
+    // Lengths and weights are strings on purpose. They are parsed into exact integers,
+    // so '0.1' means a tenth of a millimetre and never 0.09999999999999999. Plain
+    // integers and fractions like '3/16' work too.
+    { id: 'mug', quantity: 6, dimensions: { length: '120', width: '120', height: '100' }, weight: '400 g' },
+    { id: 'plate', quantity: 8, dimensions: { length: '260', width: '260', height: '20' }, weight: '600 g' },
+    // Too long for the box in every orientation, so it cannot be placed.
+    { id: 'ladder', quantity: 1, dimensions: { length: '1800', width: '300', height: '100' }, weight: '6 kg' },
+  ],
+  containers: [
+    {
+      id: 'box',
+      inner_dimensions: { length: '400', width: '400', height: '400' },
+      max_payload: '15 kg',
+      cost_minor: 180,
+    },
+  ],
+};
+
+const result = pack(request);
+
+console.log(`status: ${result.status}`);
+console.log(`containers opened: ${result.containers.length}`);
+
+for (const [index, container] of result.containers.entries()) {
+  console.log(`\nbox #${index + 1}: ${container.placements.length} placement(s), ` +
+    `${container.volume_utilization} of the volume used`);
+  for (const placement of container.placements) {
+    // Every measurement arrives as { ticks, value, unit }: `ticks` is the exact integer
+    // the engine reasoned about, `value` is that same number written for a human.
+    const { x, y, z } = placement.position;
+    console.log(
+      `  ${placement.item_type.padEnd(8)} at (${x.value}, ${y.value}, ${z.value}) ${x.unit}` +
+      `  orientation ${placement.orientation}`,
+    );
+  }
+}
+
+// A refusal is an answer, not an error. Each entry says which instance was refused and
+// the structured reason, so you can act on it rather than re-guessing.
+if (result.unpacked_items.length > 0) {
+  console.log('\nnot packed:');
+  for (const unpacked of result.unpacked_items) {
+    console.log(`  ${unpacked.item_id.padEnd(10)} ${unpacked.reason}`);
+  }
+}

package/examples/commerce.mjs

@@ -0,0 +1,163 @@
+/**
+ * Quote a shipment, apply a policy rule, and inspect a catalog version.
+ *
+ * Run it:
+ *
+ *     node examples/commerce.mjs
+ *
+ * Everything the three functions need arrives in one *commerce document*: the tariffs
+ * you publish, the eligibility rules you publish, and the catalog versions you publish.
+ * Each history is a list, and a version's number is simply its position in that list
+ * starting at 1 — so `tariff_version: 2` always means "the second entry under this
+ * carrier and service", with no separate numbering to keep in sync.
+ *
+ * `commerce` picks the native addon when @packvium/native is installed and the
+ * deterministic JavaScript engine otherwise. Both return the same answer;
+ * `commerce.backend()` says which one answered.
+ */
+
+import { commerce } from '../index.js';
+
+// One document, three histories. You would normally load this from your own storage.
+const document = {
+  tariffs: [{
+    carrier_id: 'acme',
+    service_id: 'ground',
+    // Two published versions. The second takes effect at instant 1000.
+    versions: [
+      {
+        effective_at: 0,
+        // Volume in mm^3 divided by this gives dimensional weight in grams.
+        dimensional_weight_divisor: 5000,
+        // Minor currency units (cents) per billed kilogram, per zone.
+        cost_per_dimensional_kg_minor: { 'zone-a': 450, 'zone-b': 610 },
+        minimum_charge_minor: 900,
+        // Permille: 120 means 12.0%.
+        fuel_surcharge_permille: 120,
+        accessorials: [
+          { accessorial_id: 'liftgate', flat_charge_minor: 250 },
+          { accessorial_id: 'residential', permille_of_base: 75 },
+        ],
+      },
+      {
+        effective_at: 1000,
+        dimensional_weight_divisor: 4000,
+        cost_per_dimensional_kg_minor: { 'zone-a': 480 },
+        minimum_charge_minor: 950,
+        fuel_surcharge_permille: 140,
+        accessorials: [{ accessorial_id: 'liftgate', flat_charge_minor: 275 }],
+      },
+    ],
+  }],
+  policy_rules: [{
+    rule_id: 'no-hazmat-air',
+    versions: [{
+      scope: 'hazmat',
+      action: 'reject',
+      priority: 10,
+      effective_at: 0,
+      reason: 'class 1.4 is not accepted on air services',
+      predicates: [
+        { scope: 'hazmat', field: 'un_class', operator: 'equals', value: '1.4' },
+      ],
+    }],
+  }],
+  catalogs: [{
+    catalog_id: 'dc-12',
+    versions: [
+      {
+        effective_at: 0,
+        published_at: 0,
+        note: 'initial',
+        snapshot: {
+          items: [{ id: 'sku-1', dimensions_mm: [100, 200, 300], weight_g: 1200 }],
+          cartons: [{
+            id: 'box-m', inner_dimensions_mm: [320, 240, 180],
+            max_payload_g: 15000, cost_minor: 85,
+          }],
+        },
+      },
+      // A rollback is a new, higher-numbered version, never an edit of history.
+      {
+        rollback_to: 1, published_at: 900, effective_at: 900,
+        note: 'revert the weight correction',
+      },
+    ],
+  }],
+};
+
+const show = (title, result) => {
+  console.log(`\n== ${title}`);
+  console.log(JSON.stringify(result, null, 2));
+};
+
+console.log(`backend: ${commerce.backend()}`);
+
+// 1. Quote: what does this shipment cost?
+const pinned = commerce.quote(document, {
+  carrier_id: 'acme',
+  service_id: 'ground',
+  tariff_version: 1,          // replay against exactly this version...
+  zone: 'zone-a',
+  actual_weight_g: 1200,
+  volume_mm3: 6000000,
+  requested_accessorials: ['liftgate'],
+});
+show('a quote pinned to tariff version 1', pinned);
+console.log(`   -> the caller pays ${pinned.quote.total_minor} minor units`);
+
+const effective = commerce.quote(document, {
+  carrier_id: 'acme',
+  service_id: 'ground',
+  as_of: 1500,                // ...or against whatever was in force at this instant
+  zone: 'zone-a',
+  actual_weight_g: 1200,
+  volume_mm3: 6000000,
+  requested_accessorials: ['liftgate'],
+});
+console.log(`\n   as of instant 1500 the tariff is version ${effective.quote.tariff_version},`
+  + ` and the price is ${effective.quote.total_minor}`);
+
+// A request the model cannot answer is not an exception. It is a result with a status,
+// a code from a closed set, and the structured fields that say what was missing.
+show('a zone this tariff does not price', commerce.quote(document, {
+  carrier_id: 'acme', service_id: 'ground', tariff_version: 1,
+  zone: 'zone-nowhere', actual_weight_g: 1200, volume_mm3: 6000000,
+}));
+
+// A *malformed* request is a different thing entirely: that is your bug, and it throws.
+try {
+  commerce.quote(document, {
+    carrier_id: 'acme', service_id: 'ground', tariff_version: 1,
+    zone: 'zone-a', actual_weight_g: -1, volume_mm3: 6000000,
+  });
+} catch (error) {
+  console.log(`\n   a negative weight is refused before anything is priced: ${error.message}`);
+}
+
+// 2. Policy: may this shipment go at all?
+show('a policy decision, with the rule that made it', commerce.evaluatePolicy(document, {
+  scope: 'hazmat',
+  context: { un_class: '1.4' },
+  as_of: 0,
+}));
+
+const allowed = commerce.evaluatePolicy(document, {
+  scope: 'hazmat', context: { un_class: '9' }, as_of: 0,
+});
+console.log('\n   nothing matched, so the shipment is allowed with no citation:'
+  + ` ${allowed.decision.citation}`);
+
+// 3. Catalog: which master data was this decision made against?
+const catalog = commerce.catalogVersionInfo(document, {
+  catalog_id: 'dc-12',
+  version: 2,
+  resolved_at: 1700,
+});
+show('catalog version metadata', catalog);
+console.log(`\n   version ${catalog.catalog.version} is a rollback of version`
+  + ` ${catalog.catalog.rolled_back_from}`);
+
+// Storing or comparing a result: use the canonical form, never JSON.stringify directly.
+console.log('\n== the canonical form is what you store, log and compare');
+console.log(commerce.canonicalJson(pinned));

package/examples/objectives.mjs

@@ -0,0 +1,114 @@
+/**
+ * Objectives: six ways to be "best", and the scenes where they disagree.
+ *
+ * Run it:
+ *
+ *     node examples/objectives.mjs
+ *
+ * Every solve returns the arrangement that scores best -- but "best" is a choice, and it
+ * is the one setting most likely to make the library look wrong when it is merely
+ * answering a different question than you meant to ask. This example builds scenes where
+ * two objectives genuinely pick different containers, so the difference is visible
+ * rather than asserted.
+ *
+ * The score is always a lexicographic array of exact integers, never a float, and its
+ * first key is always the unpacked count: no objective will ever leave an item behind to
+ * save money. The same request handed to the Python, PHP or Rust engine prints the same
+ * vector.
+ */
+
+import { pack } from '../index.js';
+
+const widgets = [{
+  id: 'widget', quantity: 8,
+  dimensions: { length: '100', width: '100', height: '100' },
+  weight: '500 g',
+}];
+
+const solve = (configuration, containers) => {
+  const result = pack({ units: { length: 'mm' }, configuration, items: widgets, containers });
+  const chosen = result.containers.length > 0 ? result.containers[0].container_type : 'none';
+  return `${chosen.padEnd(6)} score=${JSON.stringify(result.score)}`;
+};
+
+const box = (id, side, extra = {}) => ({
+  id,
+  inner_dimensions: { length: side, width: side, height: side },
+  max_payload: '20 kg',
+  ...extra,
+});
+
+const weightPricing = {
+  dimensional_weight_divisor: 5000,
+  dimensional_weight_length_unit: 'cm',
+  dimensional_weight_weight_unit: 'kg',
+};
+
+const snug = box('snug', '300', { cost_minor: 500 });
+const roomy = box('roomy', '400', { cost_minor: 150 });
+
+// `default` -- fewest containers, then tightest fit. What you want when the boxes are
+// interchangeable and you are simply trying not to open another one.
+console.log('default             ', solve({ seed: 42 }, [snug, roomy]));
+
+// `lowest_cost` -- the cheapest *packaging*. `cost_minor` is what the box costs you, so
+// this is the objective for a warehouse buying cartons, not a shipper paying a carrier.
+console.log('lowest_cost         ', solve({ seed: 42, objective: 'lowest_cost' }, [snug, roomy]));
+
+// `shipping_cost` -- carrier-billable *weight*: the greater of actual gross weight and
+// dimensional weight. A big light box can bill more than a small heavy one, which is why
+// this is not the same objective as `lowest_cost`. It needs a divisor and refuses rather
+// than guessing one, because a wrong divisor silently misprices every shipment.
+console.log('shipping_cost       ',
+  solve({ seed: 42, objective: 'shipping_cost', ...weightPricing }, [snug, roomy]));
+
+// `lowest_landed_cost` -- carrier-billable *money*, with the rate card arriving as
+// request data. Weight and money do not always agree: a bracket step, or a minimum
+// charge, can make the cheaper shipment the heavier one. Below the roomy box bills
+// heavier (12,800 g of dimensional weight against the snug box's 5,400) and still costs
+// less, because the snug box's carrier charges a steep first bracket.
+const dearPerGram = box('snug', '300', {
+  rate_table: { weight_brackets_g: [6000, 20000], prices_minor: [2400, 3100] },
+});
+const cheapPerGram = box('roomy', '400', {
+  rate_table: { weight_brackets_g: [6000, 20000], prices_minor: [900, 1500] },
+});
+const byMoney = { seed: 42, objective: 'lowest_landed_cost', ...weightPricing };
+console.log('lowest_landed_cost  ', solve(byMoney, [dearPerGram, cheapPerGram]));
+
+// A rate card that stops short of the shipment is a refusal, never a silent clamp to the
+// top bracket -- you would otherwise be quoted a price the carrier never published.
+const tooNarrow = box('roomy', '400', {
+  rate_table: { weight_brackets_g: [2000], prices_minor: [900] },
+});
+try {
+  solve(byMoney, [tooNarrow]);
+} catch (refusal) {
+  console.log('lowest_landed_cost* ', `refused: ${refusal.message}`);
+}
+
+// `open_dimension_height` -- pack into the shortest stack, for a lidless container or a
+// pallet that has to clear a doorway.
+console.log('open_dimension_height',
+  solve({ seed: 42, objective: 'open_dimension_height' }, [snug, roomy]));
+
+// `maximum_value` -- when not everything fits, leave the *cheap* things behind. It orders
+// by value; it does not solve the knapsack problem to optimality. `quantity: 1` on the
+// container is what makes it a choice at all -- with an unlimited supply the packer
+// simply opens another box.
+const scarce = pack({
+  units: { length: 'mm' },
+  configuration: { seed: 42, objective: 'maximum_value' },
+  items: [
+    { id: 'gold', quantity: 2, dimensions: { length: '100', width: '100', height: '100' }, weight: '500 g', value: 90000 },
+    { id: 'gravel', quantity: 2, dimensions: { length: '100', width: '100', height: '100' }, weight: '500 g', value: 10 },
+  ],
+  containers: [{
+    id: 'tiny', quantity: 1,
+    inner_dimensions: { length: '200', width: '100', height: '100' },
+    max_payload: '20 kg',
+  }],
+});
+const kept = scarce.containers.flatMap((c) => c.placements.map((p) => p.item_type)).sort();
+const left = (scarce.unpacked_items ?? []).map((u) => u.item_type ?? u.item_id).sort();
+console.log('maximum_value       ', `packed=${JSON.stringify(kept)} left behind=${JSON.stringify(left)}`);

package/fallback.js

@@ -72,6 +72,9 @@ function chargeMinor(table,grams){
 // property of the request -- this depends on how the search happened to fill the box,
 // so it must lose a candidate rather than abort the run.
 const UNPRICEABLE=Number.MAX_SAFE_INTEGER;
+// One wording for the refusal wherever it fires (outermost solve frame, rebalancing),
+// so the four engines stay literally comparable.
+const unpriceableRefusal=({id,grams,bound})=>new RangeError(`container ${JSON.stringify(id)} bills at ${grams} g, above its rate table's last bracket (${bound} g); the shipment has no published price`);
 const addLanded=(total,template,billedTicks)=>{
   if(total===UNPRICEABLE)return total;
   const charge=template.rate==null?null:chargeMinor(template.rate,billedGrams(billedTicks));
@@ -523,10 +526,12 @@ function compactGridResult(req,{u,ou,ow,clear,objective,dimensionalWeight,solver
     templates.push({...container,d:inner,outerD:outer,max:container.max_payload==null?null:scalar(container.max_payload,'g',WT),
       tare:scalar(container.tare_weight??0,'g',WT),rate:parseRateTable(container.rate_table)})
   }
-  // `lowest_landed_cost` shares this key with `shipping_cost` deliberately: when a
-  // container is opened its final billed weight is not yet known, so the tariff has
-  // nothing to price. Billable weight is the monotone proxy the key already used, and
-  // the finished answer is priced exactly below.
+  // `lowest_landed_cost` never reaches this path: packFallback forces `compact=null`
+  // for that objective (see the exclusion beside the policy-rule gate), because this
+  // path commits to one container from the billed-weight proxy with no priced
+  // alternative to correct it. The branch below is kept only so the key stays whole for
+  // `shipping_cost`, whose proxy it is; re-enabling compact for landed cost would
+  // resurrect the MAX_SAFE_INTEGER leak, since this return path has no refusal.
   templates.sort((a,b)=>objective==='shipping_cost'||objective==='lowest_landed_cost'
     ?dimensionalWeight(a.outerD)-dimensionalWeight(b.outerD)||(a.cost_minor??0)-(b.cost_minor??0)||Number(volume(a.d)-volume(b.d))
     :(a.cost_minor??0)-(b.cost_minor??0)||Number(volume(a.d)-volume(b.d)));
@@ -663,6 +668,10 @@ function compactGridResult(req,{u,ou,ow,clear,objective,dimensionalWeight,solver
       const inner=volume(template.d);if(inner>0n)scoreUnused+=Number((inner-used)*1000000n/inner);
       if(template.d[2]>0)scoreHeight+=Number(BigInt(layers*best.envelope[2])*1000000n/BigInt(template.d[2]));
       scoreAchievedHeight+=layers*best.envelope[2];
+      // `lowest_landed_cost` cannot reach this path (packFallback excludes compact for
+      // it); if it ever could again, `addLanded`'s UNPRICEABLE sentinel would flow into
+      // `score` unrefused -- this return path never checks the finished answer against
+      // the tariff the way the outermost general-path frame does.
       if(objective==='shipping_cost'||objective==='lowest_landed_cost'){
         const billed=Math.max(payload+template.tare,dimensionalWeight(template.outerD));
         if(objective==='shipping_cost')scoreBillable+=billed;else scoreLanded=addLanded(scoreLanded,template,billed);
@@ -774,6 +783,19 @@ const restartLimit=effort?.max_restarts??Number.MAX_SAFE_INTEGER;
 // a k-start request consume up to k*time_limit_ms while still reporting one portfolio
 // deadline, which is both a determinism and an observability defect.
 const deadline=sharedDeadline??new Deadline(req.configuration?.time_limit_ms??1000,clock);
+//  second review: the lowest_landed_cost refusal fires once, at the single
+// outermost frame, on the packing actually selected for return -- the same choke point
+// Rust, Python and PHP refuse at. A child solver/start run instead hands its result
+// back sentinel and all, so a portfolio sibling with a priceable answer is not aborted
+// by one run's refusal. Idempotent: the quality re-entry finalizes inside its callee.
+const finalizeOutermost=result=>{
+  if(solverAlias!==null||startIndex!==null)return result;
+  if(result.unpriceableDetail!=null)throw unpriceableRefusal(result.unpriceableDetail);
+  // Belt and braces behind the portfolio branch's own filter: a sentinel-scored run
+  // must never leave the outermost frame by any route.
+  if(result.alternatives?.length)result.alternatives=result.alternatives.filter(a=>!a.unpriceableDetail);
+  return result
+};
 if(solverAlias===null&&requestedSolvers.length===0&&(req.configuration?.solver_profile??'balanced')==='quality'){
   const child={...req,configuration:{...(req.configuration??{}),solvers:['homogeneous_blocks','extreme_points','maximal_spaces','layer']}};
   return packFallback(child,clock,null,null,deadline)
@@ -803,8 +825,9 @@ if(solverAlias===null&&requestedSolvers.length){
   winner.termination=aggregateTermination(starts);
   winner.algorithm=withPortfolioEffort(winner,runs);
   const alternativeLimit=Math.max(0,(req.configuration?.alternatives??3)-1);
-  winner.alternatives=runs.filter((_,index)=>index!==winnerIndex).sort((a,b)=>compareScore(a.score,b.score)).slice(0,alternativeLimit);
-  return winner;
+  // The sentinel is a search device, never an answer -- alternatives included ( review).
+  winner.alternatives=runs.filter((run,index)=>index!==winnerIndex&&!run.unpriceableDetail).sort((a,b)=>compareScore(a.score,b.score)).slice(0,alternativeLimit);
+  return finalizeOutermost(winner);
 }
 // This value used to be accepted and never read: raising it produced no extra
 // work and no extra start record, so a caller asking for eight restarts got one. Each
@@ -829,7 +852,7 @@ if(startIndex===null&&multiStartOrders>1){
   winner.termination=aggregateTermination(starts);
   winner.algorithm=withPortfolioEffort(winner,runs);
   if(winnerIndex>0)winner.algorithm={...winner.algorithm,solver:`${winner.algorithm.solver}:seeded_${winnerIndex}`};
-  return winner;
+  return finalizeOutermost(winner);
 }
 const u=req.units?.length??'mm',ou=req.output?.length_unit??u,ow=req.output?.weight_unit??'g',clear=scalar(req.configuration?.clearance??0,u,LEN);
 const objective=req.configuration?.objective??'default';if(!['default','lowest_cost','shipping_cost','lowest_landed_cost','open_dimension_height','maximum_value'].includes(objective))throw new RangeError(`unknown objective ${JSON.stringify(objective)}`);
@@ -1177,7 +1200,10 @@ const packExactIntoTemplate=(tmpl,itemsRemaining)=>{
     const weights=future.map(item=>profiles.get(item.id).weight).sort((a,b)=>a-b);
     const grossWeight=weights.slice(0,placeable).reduce((sum,value)=>sum+value,work.state.payload+tmpl.tare);
     const billable=objective==='shipping_cost'||objective==='lowest_landed_cost'?Math.max(grossWeight,dimensionalWeight(tmpl.outerD)):0;
-    const landed=objective==='lowest_landed_cost'?addLanded(0,tmpl,billable):0;
+    // A promotional bracket may be cheaper than a lighter bracket, so pricing the
+    // lightest possible completion is not an admissible lower bound. Tariff charges are
+    // non-negative; zero is the general money floor and only loosens this exact search.
+    const landed=0;
     const cost=tmpl.cost_minor??0;
     if(objective==='lowest_cost')return [unpackedFloor,cost,1,unused,height];
     if(objective==='shipping_cost')return [unpackedFloor,billable,1,unused,height];
@@ -1315,7 +1341,21 @@ if(containerPlanBeamWidth>1&&solverAlias!=='exact_small'){
     const trial=packIntoTemplate(tmpl,remaining);
     if(!trial.state.placements.length)continue;
     let score,better;
-    if(solverAlias==='exact_small'){
+    // `lowest_landed_cost` ranks the round in money: the trial's charge first, then
+    // estimated rounds remaining, then progress -- the key order Rust, Python and PHP
+    // use. `planScore`'s finished vector leads with unpacked count, which is
+    // right for whole plans but inverted for one round: an unpriceable-but-roomier
+    // trial out-ranked a priceable one on progress, refusing or over-paying requests
+    // the other three engines ship. The greedy loop commits the trial verbatim, so
+    // its billed weight is final here and the tariff can be read now; an unpriceable
+    // trial still sorts behind every priceable alternative via `addLanded`'s sentinel.
+    if(objective==='lowest_landed_cost'){
+      const placed=trial.state.placements.length;
+      const billed=Math.max(trial.state.payload+tmpl.tare,dimensionalWeight(tmpl.outerD));
+      score=[addLanded(0,tmpl,billed),Math.ceil(remaining.length/Math.max(placed,1)),-placed];
+      const comparison=winnerScore==null?-1:compareScore(score,winnerScore);
+      better=comparison<0||(comparison===0&&tmpl.id<winner.tmpl.id)
+    }else if(solverAlias==='exact_small'){
       score=planScore({packed:[trial.state],remaining:trial.next});
       const comparison=winnerScore==null?-1:compareScore(score,winnerScore);
       better=comparison<0||(comparison===0&&tmpl.id<winner.tmpl.id)
@@ -1365,12 +1405,33 @@ for(const c of packed){scoreCost+=c.tmpl.cost_minor??0;
   if(objective==='shipping_cost'||objective==='lowest_landed_cost'){
     const billed=Math.max(c.payload+c.tmpl.tare,dimensionalWeight(c.tmpl.outerD));
     if(objective==='shipping_cost')scoreBillable+=billed;else scoreLanded=addLanded(scoreLanded,c.tmpl,billed);}}
+// The search ranks an unpriceable packing worst so that any priceable alternative beats
+// it; reaching here means none existed in this run. Returning such a packing would
+// quote a number the carrier never published -- the one outcome `chargeMinor` refuses
+// to invent -- so the refusal fires, but once, at the outermost frame, on the packing
+// actually selected for return: a portfolio sibling with a priceable answer must not be
+// aborted by this run's refusal. Rust, Python and PHP refuse at the same single choke
+// point ( second review). The detail rides the result as a non-enumerable property
+// below, a search device that never serializes.
+let unpriceableDetail=null;
+if(objective==='lowest_landed_cost')for(const c of packed){
+  const grams=billedGrams(Math.max(c.payload+c.tmpl.tare,dimensionalWeight(c.tmpl.outerD))),table=c.tmpl.rate;
+  if(table!=null&&chargeMinor(table,grams)!=null)continue;
+  // A missing table is already refused at admission, so `0` here is unreachable rather
+  // than a real bound -- but reading a bracket off `null` would replace the refusal
+  // with a TypeError, which is the one thing a refusal must not do. Rust, Python and PHP
+  // report the same `0` on the same unreachable branch.
+  unpriceableDetail={id:c.tmpl.id,grams,bound:table==null?0:table.brackets[table.brackets.length-1]};
+  break
+}
 const status=unpacked.length?(timeLimitReached?'time_limit':'best_found'):'feasible',complete=!unpacked.length,effortLimitReached=effortExceeded();
 const solverName=solverAlias?`${solverAlias}:javascript_fallback`:'javascript_fallback';
 const starts=[{id:solverName,started:true,completed:!timeLimitReached&&!effortLimitReached,truncated:timeLimitReached||effortLimitReached,selected:true,global_deadline_reached:timeLimitReached}],termination=aggregateTermination(starts);if(effortLimitReached&&!timeLimitReached)termination.code='effort_limit';
 const scoreValueForgone=remaining.reduce((sum,i)=>sum+(i.value??0),0);
 const defaultScore=[unpacked.length,containers.length,scoreCost,scoreUnused,scoreHeight],score=objective==='lowest_cost'?[defaultScore[0],defaultScore[2],defaultScore[1],defaultScore[3],defaultScore[4]]:objective==='shipping_cost'?[defaultScore[0],scoreBillable,defaultScore[1],defaultScore[3],defaultScore[4]]:objective==='lowest_landed_cost'?[defaultScore[0],scoreLanded,defaultScore[1],defaultScore[3],defaultScore[4]]:objective==='open_dimension_height'?[defaultScore[0],scoreAchievedHeight,defaultScore[1],defaultScore[2],defaultScore[3]]:objective==='maximum_value'?[defaultScore[0],scoreValueForgone,defaultScore[1],defaultScore[2],defaultScore[3]]:defaultScore;
-return {status,feasibility:{code:complete?'feasible':'unknown'},termination,optimality:{code:complete?'not_proven':'best_found'},complete,objective,algorithm:{profile:req.configuration?.solver_profile??'balanced',solver:solverName,duration_ms:0,seed:req.configuration?.seed??42,time_limit_reached:timeLimitReached,effort_limit_reached:effortLimitReached,candidates_evaluated:metrics.feasible_candidates,placements_attempted:metrics.orientations_considered,metrics},summary:{container_count:containers.length,packed_item_count:items.length-unpacked.length,unpacked_item_count:unpacked.length},score,containers,unpacked_items:unpacked,catalog_versions_used:catalogVersionsUsed(req.catalog_versions_used),warnings:['JavaScript fallback is active; build the Rust addon for the native portfolio'],alternatives:[]}}
+const result={status,feasibility:{code:complete?'feasible':'unknown'},termination,optimality:{code:complete?'not_proven':'best_found'},complete,objective,algorithm:{profile:req.configuration?.solver_profile??'balanced',solver:solverName,duration_ms:0,seed:req.configuration?.seed??42,time_limit_reached:timeLimitReached,effort_limit_reached:effortLimitReached,candidates_evaluated:metrics.feasible_candidates,placements_attempted:metrics.orientations_considered,metrics},summary:{container_count:containers.length,packed_item_count:items.length-unpacked.length,unpacked_item_count:unpacked.length},score,containers,unpacked_items:unpacked,catalog_versions_used:catalogVersionsUsed(req.catalog_versions_used),warnings:['JavaScript fallback is active; build the Rust addon for the native portfolio'],alternatives:[]};
+if(unpriceableDetail!=null)Object.defineProperty(result,'unpriceableDetail',{value:unpriceableDetail,enumerable:false,writable:false,configurable:true});
+return finalizeOutermost(result)}
 
 function resultTicks(value,name){
   const ticks=value&&typeof value==='object'&&Number.isSafeInteger(value.ticks)?value.ticks:null;
@@ -1519,8 +1580,39 @@ function publicRebalancedContainers(req,context){
  */
 export function rebalanceWeight(req,result,{maxMoves=64}={}){
   if(!Number.isSafeInteger(maxMoves)||maxMoves<0)throw new RangeError('maxMoves must be a non-negative safe integer');
+  const objective=req.configuration?.objective??'default',dimDivisor=req.configuration?.dimensional_weight_divisor??null;
+  if((objective==='shipping_cost'||objective==='lowest_landed_cost')&&dimDivisor==null)throw new RangeError(`the ${objective} objective requires configuration.dimensional_weight_divisor`);
+  if(objective==='lowest_landed_cost'){
+    const unrated=(req.containers??[]).find(container=>container.rate_table==null);
+    if(unrated!=null)throw new RangeError(`the lowest_landed_cost objective requires a rate_table on every container; ${JSON.stringify(unrated.id)} has none`)
+  }
   const context=rebalanceContext(req,result),moves=[];
   if(!rebalanceValid(context,result))throw new TypeError('result is not a valid packing of this request');
+  //  second review: under `lowest_landed_cost` a move is a re-pricing -- shifting
+  // payload can push a destination past its rate table's last bracket, leaving the
+  // "balanced" packing with no published price. States are priced with the same helpers
+  // the packer bills with: an unpriceable input is refused up front in the standard
+  // words, and a trial that turns any state unpriceable fails exactly like an invalid
+  // one. Gated on the objective and divisor so every other request is byte-identical.
+  let statesPriceable=null;
+  if(objective==='lowest_landed_cost'){
+    const lengthUnit=req.configuration?.dimensional_weight_length_unit??'in',weightUnit=req.configuration?.dimensional_weight_weight_unit??'lb';
+    const dimensionalTicks=d=>Number(volume(d)*BigInt(WT[weightUnit])/(BigInt(LEN[lengthUnit])**3n*BigInt(dimDivisor)));
+    // rebalanceContext keeps the raw rate_table; parse it once per container type with
+    // the packer's own parser so both entry points refuse the same malformed tariffs.
+    const pricing=new Map();
+    const priceEntry=tmpl=>{
+      let entry=pricing.get(tmpl.id);
+      if(entry===undefined){entry={rate:parseRateTable(tmpl.rate_table),dimTicks:dimensionalTicks(tmpl.outerD)};pricing.set(tmpl.id,entry)}
+      return entry};
+    const unpriceableState=state=>{
+      const entry=priceEntry(state.tmpl),payload=state.placements.reduce((total,placement)=>total+placement.item.w,0);
+      const grams=billedGrams(Math.max(payload+state.tmpl.tare,entry.dimTicks));
+      if(entry.rate!=null&&chargeMinor(entry.rate,grams)!=null)return null;
+      return {id:state.tmpl.id,grams,bound:entry.rate==null?0:entry.rate.brackets[entry.rate.brackets.length-1]}};
+    statesPriceable=()=>context.states.every(state=>unpriceableState(state)==null);
+    for(const state of context.states){const detail=unpriceableState(state);if(detail!=null)throw unpriceableRefusal(detail)}
+  }
   for(let moveNumber=0;moveNumber<maxMoves;moveNumber++){
     if(context.states.length<2)break;
     const weights=context.states.map(state=>state.placements.reduce((total,placement)=>total+placement.item.w,0));
@@ -1540,7 +1632,7 @@ export function rebalanceWeight(req,result,{maxMoves=64}={}){
           const [relocated]=trial[sourceIndex].placements.splice(placementIndex,1);
           relocated.x=x;relocated.y=y;relocated.z=z;trial[destinationIndex].placements.push(relocated);
           const originalStates=context.states;context.states=trial;
-          if(rebalanceValid(context,result)){
+          if(rebalanceValid(context,result)&&(statesPriceable==null||statesPriceable())){
             committed={item_id:moving.item.id,from_container_id:originalStates[sourceIndex].publicContainer.id,to_container_id:originalStates[destinationIndex].publicContainer.id};
             break search
           }

package/index.d.ts

@@ -51,3 +51,15 @@ export function packJson(input:string):string;
 export function rebalanceWeight(request:PackingRequest,result:PackingResult,options?:{maxMoves?:number}):RebalanceResult;
 export function backend():"rust"|"javascript";
 export function version():string;
+/** One canonical commerce result document: see docs/COMMERCE-API.md. */
+export type CommerceResult=Record<string,unknown>;
+export class CommerceInputError extends Error{readonly name:'CommerceInputError'}
+export const commerce:{
+  backend():"rust"|"javascript";
+  readonly API_VERSION:number;
+  readonly REJECTION_CODES:readonly string[];
+  canonicalJson(result:CommerceResult):string;
+  quote(document:unknown,request:unknown):CommerceResult;
+  evaluatePolicy(document:unknown,request:unknown):CommerceResult;
+  catalogVersionInfo(document:unknown,request:unknown):CommerceResult;
+};

package/index.js

@@ -14,6 +14,8 @@ export {
   explanationForUnpackedItem, explainUnpackedItem,
 } from './fallback.js';
 export { UnsupportedFeatureError };
+import * as commerceFallback from './commerce.js';
+export { CommerceInputError } from './commerce.js';
 const require=createRequire(import.meta.url);
 let native=null;
 for(const candidate of ['./packvium-native.node','@packvium/native']){try{native=require(candidate);break}catch{}}
@@ -27,4 +29,42 @@ export function rebalanceWeight(request,result,{maxMoves=64}={}){
   }
   return rebalanceFallback(request,result,{maxMoves});
 }
-export const version=()=>native?.version?.()??'0.1.0-js-fallback';
+export const version=()=>native?.version?.()??'0.1.2-js-fallback';
+
+/**
+ * The exported commercial and control-plane API: a quote, a policy decision and catalog
+ * version metadata over one canonical JSON document (docs/COMMERCE-API.md).
+ *
+ * Native-first with a deterministic JavaScript fallback, the same backend selection the
+ * packing entry points use. The two agree on every shared fixture; `backend()` reports
+ * which one answered a `pack`, and `commerce.backend()` which one answers these.
+ */
+export const commerce = {
+  backend: () => (native?.commerceQuoteJson ? 'rust' : 'javascript'),
+  API_VERSION: commerceFallback.API_VERSION,
+  REJECTION_CODES: commerceFallback.REJECTION_CODES,
+  canonicalJson: commerceFallback.canonicalJson,
+  quote: (document, request) =>
+    viaNative(native?.commerceQuoteJson, document, request) ?? commerceFallback.quote(document, request),
+  evaluatePolicy: (document, request) =>
+    viaNative(native?.commerceEvaluatePolicyJson, document, request)
+      ?? commerceFallback.evaluatePolicy(document, request),
+  catalogVersionInfo: (document, request) =>
+    viaNative(native?.commerceCatalogVersionInfoJson, document, request)
+      ?? commerceFallback.catalogVersionInfo(document, request),
+};
+
+/**
+ * Call one native commerce entry point, or report that there is none.
+ *
+ * A native input error is re-thrown as the same `CommerceInputError` the fallback
+ * raises, so a caller never has to know which backend answered to catch the failure.
+ */
+function viaNative(entry, document, request) {
+  if (!entry) return null;
+  try {
+    return JSON.parse(entry(JSON.stringify({ document, request })));
+  } catch (error) {
+    throw new commerceFallback.CommerceInputError(error.message);
+  }
+}

package/package.json

@@ -1,14 +1,18 @@
 {
   "name":"@packvium/engine",
-  "version":"0.1.0",
+  "version":"0.1.2",
   "description":"Native-first 3D cartonization with deterministic JS fallback",
+  "keywords":["3d-bin-packing","bin-packing","cartonization","packing","container-loading","logistics","shipping","deterministic"],
+  "homepage":"https://github.com/toxakara/packvium-node#readme",
+  "repository":{"type":"git","url":"git+https://github.com/toxakara/packvium-node.git"},
+  "bugs":{"url":"https://github.com/toxakara/packvium-node/issues"},
   "type":"module",
   "main":"index.js",
   "types":"index.d.ts",
   "exports":{".":{"types":"./index.d.ts","import":"./index.js"}},
-  "files":["index.js","fallback.js","contact-graph.js","policy.js","index.d.ts","README.md"],
+  "files":["index.js","fallback.js","contact-graph.js","policy.js","commerce.js","commerce-model.js","examples","index.d.ts","README.md","SECURITY.md"],
   "engines":{"node":">=16"},
-  "optionalDependencies":{"@packvium/native":"0.1.0"},
+  "optionalDependencies":{"@packvium/native":"0.1.2"},
   "scripts":{
     "test":"node --test \"test/*.test.mjs\"",
     "test:legacy":"node test/legacy-conformance.mjs"