From 7c5fb506bd4bc21244fb6be575b6893727c195dd Mon Sep 17 00:00:00 2001
From: Anton Kara <anton@visentor.com>
Date: Thu, 20 Aug 2026 12:49:29 -0400
Subject: [PATCH] chore(release): sync 0.1.1 from workspace

---
 .DS_Store                              | Bin 6148 -> 0 bytes
 .gitignore                             |   4 +
 CHANGELOG.md                           |  43 ++
 README.md                              |  80 ++-
 commerce-model.js                      | 236 +++++++++
 commerce.js                            | 664 +++++++++++++++++++++++++
 docs/COMMERCE-API.md                   | 392 +++++++++++++++
 docs/GUARANTEES.md                     |   2 +-
 docs/PUBLIC-API.md                     |  32 ++
 docs/README.md                         |   1 +
 examples/basic.mjs                     |  67 +++
 examples/commerce.mjs                  | 163 ++++++
 fallback.js                            | 114 ++++-
 index.d.ts                             |  12 +
 index.js                               |  42 +-
 package.json                           |   6 +-
 policy.js                              | 226 +++++++++
 test/commerce-edge-cases.test.mjs      | 303 +++++++++++
 test/commerce-native-dispatch.test.mjs | 157 ++++++
 test/commerce.test.mjs                 | 202 ++++++++
 test/fallback.test.mjs                 | 371 +++++++++++++-
 test/force-fallback.cjs                |  16 +-
 22 files changed, 3105 insertions(+), 28 deletions(-)
 delete mode 100644 .DS_Store
 create mode 100644 .gitignore
 create mode 100644 commerce-model.js
 create mode 100644 commerce.js
 create mode 100644 docs/COMMERCE-API.md
 create mode 100644 examples/basic.mjs
 create mode 100644 examples/commerce.mjs
 create mode 100644 policy.js
 create mode 100644 test/commerce-edge-cases.test.mjs
 create mode 100644 test/commerce-native-dispatch.test.mjs
 create mode 100644 test/commerce.test.mjs

diff --git a/.DS_Store b/.DS_Store
deleted file mode 100644
index 6aee0c58e40f56649155b3319d7b7cb969786cea..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 6148
zcmeHKy-or_5T3<L#MqEnV7aB0fyVkE=M&Ib8AQPZawI@vVso{fozG%tXM6#pl@FlL
zpx^8)cY7RI8lyAG?6;Ypow@Jec9)1ucQI%aHHfGVWvuOBSR?Fbtw_yVIN9(T<6*mZ
zmQJRXNHzRc2Ke1YbVx(Gq<Q)MUEGJhNtz`6aoUHietUFt_tJdql>LKm{nJtK+b}Uw
zX?t0hMzo-Qx%%E)H6rYx^>Ow2EIq8OGf9h1Hb<5EA&X+*VL&OJ(X8Cb=som>J=mw~
zWe<67Sbd$pTsM=tb2_Kl3jgMn|3?vdUs(5{**Q2_@}K*Qr(WkT)vdL-u8K0C4E$dP
zuxGQ>cLjA+29yD1AZLKT4;IQ8d&~sgrvrn#0steJonX#KO3tw!V~?32JP;$PKuI<J
zieV%jcI)F}kC~vPlkt}i<0~6~Lou#8*0(O4<fJKc9hCuPpkQE2rVZZzk2l}{iv*o1
z1IoakW57g7FX`g3{N7r5K;COD^c2d%ahYJAf{ELT5zAZgKGX^9mM6g2V<rd-L=OUv
L1|5`vA7$VRUfzM+

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..81d50d2
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+.DS_Store
+node_modules/
+*.tgz
+packvium-native.node
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 548f424..bb1897f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,49 @@ The format follows [Keep a Changelog](https://keepachangelog.com/1.1.0/) and thi
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — with the caveat
 that the public API is not frozen until `1.0.0`. Pin an exact version.
 
+## [0.1.1]
+
+A patch over `0.1.0`. Every package is released together at the new version, including
+the ones `0.1.0` did not break, so that one version number still describes one tested
+set.
+
+### Fixed
+
+- **`lowest_landed_cost` could choose a container its own rate card cannot price.** When
+  one container billed lighter than another but its rate table ran out before the
+  shipment's billed weight, the search preferred it — returning the one packing you
+  cannot actually buy over a priced alternative. Every engine now compares candidates by
+  the money the rate table charges rather than by billed weight, which also fixes the
+  case this objective exists for: a bracket step or a minimum charge can make the
+  cheaper shipment the heavier one. If no container on offer can price the load, the
+  request is refused with a message naming the container, its billed weight and the last
+  bracket, in all four languages — previously two of them returned a result carrying a
+  sentinel cost, and two aborted requests that had a shippable answer. `RateTable` gains
+  a non-throwing `charge_minor_or_none` / `chargeMinorOrNull`; the throwing form is
+  unchanged. No request or result field changed.
+
+- **`@packvium/engine@0.1.0` could not be imported.** The published tarball was missing
+  a runtime module that the fallback engine imports, so the first `import` of the package
+  threw `ERR_MODULE_NOT_FOUND`. npm versions are immutable, which is why the fix has to
+  arrive as a new version rather than a re-upload. Package assembly now dry-packs the
+  tarball and resolves every relative import in the real published inventory, so a
+  missing runtime file fails the release build instead of the consumer's first import.
+  Only the Node package was affected; the Python, PHP and Rust `0.1.0` releases install
+  and run correctly.
+
+### Added
+
+- **Commercial and control-plane API.** Three deterministic functions over one canonical
+  JSON document: `quote` returns a landed cost together with the tariff version that
+  produced it, `evaluate_policy` returns an eligibility decision together with the rule id
+  and version that decided it, and `catalog_version_info` returns the metadata of one
+  pinned catalog version. Exported as `packvium.commerce` (Python), `Packvium\Commerce\`
+  (PHP), `packvium_core::commerce` (Rust, plus three C ABI entry points) and `commerce`
+  on `@packvium/engine` and `@packvium/browser`. Prices are exact integers in minor
+  currency units and every inexact division rounds up, so a quote is reproducible rather
+  than approximately equal. No packing-request or packing-result field changed. Each
+  package ships a runnable `commerce` example; the contract is in `docs/COMMERCE-API.md`.
+
 ## [0.1.0]
 
 First release.
diff --git a/README.md b/README.md
index 5c322da..de19369 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ production.
 ## Quick start
 
 ```js
-import { backend, pack } from '@packvium/engine';
+import { backend, commerce, pack } from '@packvium/engine';
 
 const result = pack({
   items: [{
@@ -31,6 +31,79 @@ const result = pack({
 console.log(backend());       // "rust" or "javascript"
 console.log(result.status);   // "feasible"
 console.log(result.containers);
+
+const commerceDocument = { tariffs: [{
+  carrier_id: 'acme', service_id: 'ground',
+  versions: [{
+    effective_at: 0, dimensional_weight_divisor: 5000,
+    cost_per_dimensional_kg_minor: { 'zone-a': 450 },
+    minimum_charge_minor: 900, fuel_surcharge_permille: 120,
+  }],
+}] };
+const quote = commerce.quote(commerceDocument, {
+  carrier_id: 'acme', service_id: 'ground', tariff_version: 1,
+  zone: 'zone-a', actual_weight_g: 1200, volume_mm3: 6000000,
+});
+console.log(quote.quote.total_minor);
+```
+
+## Quotes, policy and catalog versions
+
+`commerce` has three functions, all deterministic and all over one document you supply —
+no clock, no network, no hidden state. A history is a list and a version's number is its
+position in that list starting at 1, so `tariff_version: 2` always means "the second
+entry under this carrier and service".
+
+```js
+import { commerce } from '@packvium/engine';
+
+// Which version applies: pin it, or ask what was in force at an instant. Never both.
+commerce.quote(document, { /* ... */ tariff_version: 1 });
+commerce.quote(document, { /* ... */ as_of: 1500 });
+
+// The decision, and the rule id and version that made it.
+const { decision } = commerce.evaluatePolicy(document, {
+  scope: 'hazmat', context: { un_class: '1.4' }, as_of: 0,
+});
+decision.allowed;              // false
+decision.citation.rule_id;     // "no-hazmat-air"
+
+// Which catalog version a pin resolves to, what it holds, whether it was a rollback.
+const { catalog } = commerce.catalogVersionInfo(document, {
+  catalog_id: 'dc-12', version: 2, resolved_at: 1700,
+});
+catalog.entry_counts;          // { items: 1, cartons: 1, pallets: 0, ... }
+catalog.rolled_back_from;      // 1, or null for an ordinary publication
+
+// Store, log and compare results in the canonical form, not JSON.stringify.
+commerce.canonicalJson(result);
+```
+
+Two kinds of failure, and they are not interchangeable:
+
+- a **malformed** document or request is your bug and throws `CommerceInputError`;
+- a request the model simply **cannot answer** — no tariff effective at that instant, no
+  rate for that zone — is a successful call returning `"status": "rejected"` with a code
+  from a closed set and structured fields naming what was missing.
+
+`commerce.backend()` reports whether the native addon or the JavaScript implementation
+answered; both return the same result for the same input. A runnable walk-through of all
+three functions is in [examples/commerce.mjs](examples/commerce.mjs), and the full
+contract — document format, every result shape, all ten rejection codes, complexity and
+limitations — is `docs/COMMERCE-API.md`.
+
+## Examples
+
+Runnable, in [`examples/`](examples). Each one is a single file you can read top to bottom
+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. |
+| [`commerce.mjs`](examples/commerce.mjs) | Rate a shipment, apply an eligibility rule, and pin a catalog version. |
+
+```bash
+node examples/basic.mjs
 ```
 
 ## Features
@@ -41,6 +114,8 @@ console.log(result.containers);
 - JSON input/output through `pack()` or `packJson()`.
 - Optional payload rebalancing with `rebalanceWeight()`.
 - Loading and removal sequence helpers for already placed boxes.
+- Deterministic carrier quotes, policy evaluation and effective-dated catalog lookup
+  through `commerce`.
 
 The native addon is optional. `npm install` works on unsupported platforms too; call
 `backend()` if your application needs to know which implementation handled a request.
@@ -48,7 +123,8 @@ The native addon is optional. `npm install` works on unsupported platforms too;
 ## API and support
 
 TypeScript declarations are included. See the package's `index.d.ts` for the complete
-request and result types. Report security issues through [SECURITY.md](SECURITY.md).
+request and result types, and `docs/COMMERCE-API.md` for the commercial/control-plane
+contract. Report security issues through [SECURITY.md](SECURITY.md).
 
 ## License
 
diff --git a/commerce-model.js b/commerce-model.js
new file mode 100644
index 0000000..2a61c58
--- /dev/null
+++ b/commerce-model.js
@@ -0,0 +1,236 @@
+/**
+ * The commercial and control-plane models: carrier rating, eligibility policy and
+ * catalog versioning.
+ *
+ * An independent implementation of the contract in docs/COMMERCE-API.md, held to
+ * producing a valid result that meets each shared fixture's objective floor. For a
+ * quote that floor is an exact integer price, so matching it means matching exactly.
+ *
+ * Money, weight and volume arithmetic runs in BigInt and every inexact division rounds
+ * up, so a quote can neither drift through a double nor land a minor unit below what
+ * the tariff charges. Results are converted back to Number at the boundary; a component
+ * beyond Number.MAX_SAFE_INTEGER is refused rather than silently rounded.
+ *
+ * This module is package-internal: package.json exports only the root entry point.
+ */
+
+export class CommerceInputError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CommerceInputError';
+  }
+}
+
+/** Exact ceil(a * b / d) for non-negative inputs, in BigInt so nothing can wrap. */
+export function ceilMulDiv(a, b, d) {
+  const divisor = BigInt(d);
+  if (divisor <= 0n) throw new CommerceInputError('divisor must be positive');
+  const product = BigInt(a) * BigInt(b);
+  return (product + divisor - 1n) / divisor;
+}
+
+/** Convert an exact BigInt back to a JSON number, refusing a value a double cannot hold. */
+export function exact(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number)) {
+    throw new CommerceInputError(
+      `${value} is outside JavaScript's exact integer range; this quote cannot be represented`,
+    );
+  }
+  return number;
+}
+
+/**
+ * Order two strings by Unicode code point, the way every other implementation orders
+ * them.
+ *
+ * JavaScript's default string comparison is by UTF-16 code unit, which disagrees with
+ * Python, PHP and Rust for any character outside the Basic Multilingual Plane: an emoji
+ * (U+1F600) sorts *before* a fullwidth Latin A (U+FF21) by code unit and *after* it by
+ * code point. Sorted id lists are part of this contract's answer, so a default `.sort()`
+ * would make this implementation disagree with the other three on exactly those inputs.
+ */
+export function compareCodePoints(left, right) {
+  const a = Array.from(left);
+  const b = Array.from(right);
+  const shared = Math.min(a.length, b.length);
+  for (let index = 0; index < shared; index += 1) {
+    const difference = a[index].codePointAt(0) - b[index].codePointAt(0);
+    if (difference !== 0) return difference < 0 ? -1 : 1;
+  }
+  if (a.length === b.length) return 0;
+  return a.length < b.length ? -1 : 1;
+}
+
+// ------------------------------------------------------------------------------ rating
+
+/** The charge one accessorial adds, given the base charge it may be a permille of. */
+export function accessorialCharge(accessorial, baseChargeMinor) {
+  if (accessorial.flatChargeMinor !== null) return BigInt(accessorial.flatChargeMinor);
+  return ceilMulDiv(baseChargeMinor, accessorial.permilleOfBase, 1000);
+}
+
+/**
+ * Rate a request against one already-resolved immutable tariff version.
+ *
+ * Returns either `{breakdown}` or `{rejection}`, where a rejection names structurally
+ * what was missing -- never a silently-zero charge.
+ */
+export function rateTariff(tariff, request) {
+  if (!Object.hasOwn(tariff.costPerDimensionalKgMinor, request.zone)) {
+    return { rejection: { kind: 'zone', zone: request.zone } };
+  }
+  const unknown = request.requestedAccessorials
+    .filter((id) => !Object.hasOwn(tariff.accessorials, id))
+    .sort(compareCodePoints);
+  if (unknown.length > 0) return { rejection: { kind: 'accessorial', accessorialIds: unknown } };
+
+  // Dimensional weight in grams is volume (mm^3) over the divisor, rounded up.
+  const dimensionalWeightG = ceilMulDiv(request.volumeMm3, 1, tariff.dimensionalWeightDivisor);
+  const billedWeightG =
+    BigInt(request.actualWeightG) > dimensionalWeightG
+      ? BigInt(request.actualWeightG)
+      : dimensionalWeightG;
+
+  const rawBaseChargeMinor = ceilMulDiv(
+    billedWeightG, tariff.costPerDimensionalKgMinor[request.zone], 1000,
+  );
+  const minimumChargeApplied = rawBaseChargeMinor < BigInt(tariff.minimumChargeMinor);
+  const baseChargeMinor = minimumChargeApplied
+    ? BigInt(tariff.minimumChargeMinor)
+    : rawBaseChargeMinor;
+
+  const fuelSurchargeMinor = ceilMulDiv(baseChargeMinor, tariff.fuelSurchargePermille, 1000);
+  const accessorialCharges = request.requestedAccessorials.map((id) => [
+    id, accessorialCharge(tariff.accessorials[id], baseChargeMinor),
+  ]);
+  const accessorialTotal = accessorialCharges.reduce((sum, [, amount]) => sum + amount, 0n);
+
+  return {
+    breakdown: {
+      carrier_id: tariff.carrierId,
+      service_id: tariff.serviceId,
+      tariff_version: tariff.version,
+      zone: request.zone,
+      actual_weight_g: request.actualWeightG,
+      dimensional_weight_g: exact(dimensionalWeightG),
+      billed_weight_g: exact(billedWeightG),
+      base_charge_minor: exact(baseChargeMinor),
+      minimum_charge_applied: minimumChargeApplied,
+      fuel_surcharge_minor: exact(fuelSurchargeMinor),
+      accessorial_charges_minor: accessorialCharges.map(([id, amount]) => [id, exact(amount)]),
+      total_minor: exact(baseChargeMinor + fuelSurchargeMinor + accessorialTotal),
+    },
+  };
+}
+
+/**
+ * The version effective at `asOf`: the highest `effective_at` not after it, ties broken
+ * by the higher (later-published) version number. Null when nothing has taken effect.
+ */
+export function effectiveVersion(history, asOf, numberOf) {
+  let winner = null;
+  for (const candidate of history) {
+    if (candidate.effectiveAt > asOf) continue;
+    if (
+      winner === null
+      || candidate.effectiveAt > winner.effectiveAt
+      || (candidate.effectiveAt === winner.effectiveAt && numberOf(candidate) > numberOf(winner))
+    ) {
+      winner = candidate;
+    }
+  }
+  return winner;
+}
+
+// ------------------------------------------------------------------------------ policy
+
+export const POLICY_SCOPES = [
+  'facility', 'customer', 'carrier', 'material', 'hazmat', 'temperature', 'service',
+];
+export const POLICY_OPERATORS = ['equals', 'not_equals', 'in', 'not_in', 'exists', 'absent'];
+export const POLICY_ACTIONS = ['allow', 'reject'];
+const UNARY_OPERATORS = ['exists', 'absent'];
+
+export function isUnary(operator) {
+  return UNARY_OPERATORS.includes(operator);
+}
+
+/**
+ * Value equality over the JSON scalar types, matching the reference implementation
+ * exactly -- including that a boolean equals the integer it stands for, the one place a
+ * naive `===` would disagree and quietly change a decision.
+ */
+export function valuesEqual(left, right) {
+  if (typeof left === 'boolean' || typeof right === 'boolean') {
+    if (typeof left === 'boolean' && typeof right === 'boolean') return left === right;
+    const other = typeof left === 'boolean' ? right : left;
+    return typeof other === 'number' && Number(left) === Number(right);
+  }
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((entry, index) => valuesEqual(entry, right[index]));
+  }
+  if (Array.isArray(left) || Array.isArray(right)) return false;
+  if (left === null || right === null) return left === right;
+  if (typeof left !== typeof right) return false;
+  return left === right;
+}
+
+function contains(haystack, needle) {
+  if (Array.isArray(haystack)) return haystack.some((entry) => valuesEqual(entry, needle));
+  if (typeof haystack === 'string') return typeof needle === 'string' && haystack.includes(needle);
+  return false;
+}
+
+export function predicateMatches(predicate, context) {
+  const present = Object.hasOwn(context, predicate.field);
+  if (predicate.operator === 'exists') return present;
+  if (predicate.operator === 'absent') return !present;
+  if (!present) return false;
+  const actual = context[predicate.field];
+  switch (predicate.operator) {
+    case 'equals': return valuesEqual(actual, predicate.value);
+    case 'not_equals': return !valuesEqual(actual, predicate.value);
+    case 'in': return contains(predicate.value, actual);
+    default: return !contains(predicate.value, actual);
+  }
+}
+
+export function ruleMatches(rule, context) {
+  return rule.predicates.every((predicate) => predicateMatches(predicate, context));
+}
+
+/**
+ * Evaluate an already-resolved immutable rule set.
+ *
+ * Deny takes precedence: an explicit REJECT always outranks an ALLOW for the same
+ * context. Among equals the highest priority wins, ties break on the lexicographically
+ * smallest rule id, and nothing matching at all is allowed with no citation.
+ */
+export function decide(rules, scope, context) {
+  const matching = rules.filter((rule) => rule.scope === scope && ruleMatches(rule, context));
+  const rejects = matching.filter((rule) => rule.action === 'reject');
+  const pool = rejects.length > 0 ? rejects : matching;
+  if (pool.length === 0) return { scope, allowed: true, citation: null };
+
+  // Ties break on the lexicographically smallest rule id -- by code point, because a
+  // default `<` on strings compares UTF-16 code units and would cite a different rule
+  // than the other three implementations whenever an id leaves the Basic Multilingual
+  // Plane.
+  const winner = pool.reduce((best, rule) => (
+    rule.priority > best.priority
+    || (rule.priority === best.priority && compareCodePoints(rule.ruleId, best.ruleId) < 0)
+      ? rule : best
+  ));
+  return {
+    scope,
+    allowed: winner.action === 'allow',
+    citation: {
+      rule_id: winner.ruleId,
+      version: winner.version,
+      action: winner.action,
+      priority: winner.priority,
+      reason: winner.reason,
+    },
+  };
+}
diff --git a/commerce.js b/commerce.js
new file mode 100644
index 0000000..b578438
--- /dev/null
+++ b/commerce.js
@@ -0,0 +1,664 @@
+/**
+ * Packvium's exported commercial and control-plane API for JavaScript.
+ *
+ * Three deterministic functions over one canonical JSON document: a quote, a policy
+ * decision and catalog version metadata. The contract -- document format, result
+ * shapes, the closed set of rejection codes, complexity and limitations -- is
+ * docs/COMMERCE-API.md.
+ *
+ * Parsing is strict in both directions: a missing required key and an unrecognised
+ * extra key are both a CommerceInputError, because a field the contract does not define
+ * must never be silently ignored. A well-formed request the commercial model simply
+ * cannot answer is not an error at all -- it is a result document whose status is
+ * "rejected", the same way an infeasible packing request returns a result with a status.
+ *
+ * This module is package-internal: package.json exports only the root entry point,
+ * which re-exports these as `commerce`.
+ */
+
+import {
+  CommerceInputError,
+  compareCodePoints,
+  POLICY_ACTIONS,
+  POLICY_OPERATORS,
+  POLICY_SCOPES,
+  decide,
+  effectiveVersion,
+  isUnary,
+  rateTariff,
+} from './commerce-model.js';
+
+export { CommerceInputError };
+
+export const API_VERSION = 1;
+
+/** The closed set of rejection codes, in the order docs/COMMERCE-API.md tabulates them. */
+export const REJECTION_CODES = [
+  'tariff_not_found',
+  'no_effective_tariff',
+  'unavailable_zone',
+  'unavailable_accessorial',
+  'policy_rule_not_found',
+  'policy_version_not_found',
+  'catalog_not_found',
+  'catalog_version_not_found',
+  'no_effective_catalog_version',
+  'ambiguous_catalog_reference',
+];
+
+const EXCLUSION_SCOPES = ['item_carton', 'item_pallet'];
+const OVERRIDE_KINDS = ['carton', 'item', 'pallet'];
+
+// ------------------------------------------------------------------- shape primitives
+
+function fail(path, message) {
+  throw new CommerceInputError(`${path}: ${message}`);
+}
+
+function asObject(value, path) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    fail(path, 'expected an object');
+  }
+  return value;
+}
+
+function asList(value, path) {
+  if (!Array.isArray(value)) fail(path, 'expected a list');
+  return value;
+}
+
+function asInteger(value, path) {
+  // A JSON boolean where an exact integer belongs is a caller mistake, not a 0 or a 1.
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    fail(path, 'expected an exact integer');
+  }
+  return value;
+}
+
+function asText(value, path) {
+  if (typeof value !== 'string') fail(path, 'expected a string');
+  return value;
+}
+
+function checkKeys(value, path, required, optionalKeys = []) {
+  const missing = required.filter((key) => !Object.hasOwn(value, key)).sort();
+  if (missing.length > 0) fail(path, `missing required key(s) ${JSON.stringify(missing)}`);
+  const unknown = Object.keys(value)
+    .filter((key) => !required.includes(key) && !optionalKeys.includes(key))
+    .sort();
+  if (unknown.length > 0) fail(path, `unrecognised key(s) ${JSON.stringify(unknown)}`);
+}
+
+/** An absent or explicitly-null optional field reads as absent, in every language. */
+function optional(value, key) {
+  const found = value[key];
+  return found === undefined || found === null ? undefined : found;
+}
+
+function asAxes(value, path, count) {
+  const entries = asList(value, path);
+  if (entries.length !== count) fail(path, `expected exactly ${count} axes`);
+  return entries.map((entry, index) => asInteger(entry, `${path}[${index}]`));
+}
+
+function asEnum(value, path, allowed, label) {
+  const found = asText(value, path);
+  if (!allowed.includes(found)) fail(path, `unsupported ${label} '${found}'`);
+  return found;
+}
+
+function positive(value, path, message) {
+  if (value <= 0) fail(path, message);
+  return value;
+}
+
+function nonNegative(value, path, message) {
+  if (value < 0) fail(path, message);
+  return value;
+}
+
+function requireUniqueIds(entries, label, path) {
+  const ids = entries.map((entry) => entry.id);
+  if (new Set(ids).size !== ids.length) fail(path, `duplicate ${label} ids in catalog snapshot`);
+}
+
+/**
+ * The shared shape of all three histories: a list of `{...identity, versions: [...]}`
+ * entries, keyed by identity, where a version's number is its 1-based position.
+ */
+function loadHistories(value, path, identityKeys, label, parseVersion) {
+  const histories = new Map();
+  asList(value, path).forEach((entry, index) => {
+    const entryPath = `${path}[${index}]`;
+    const fields = asObject(entry, entryPath);
+    checkKeys(fields, entryPath, [...identityKeys, 'versions']);
+    const identity = identityKeys.map((name) => asText(fields[name], `${entryPath}.${name}`));
+    const key = identity.join('/');
+    if (histories.has(key)) fail(entryPath, `duplicate ${label} history for '${key}'`);
+    const versions = asList(fields.versions, `${entryPath}.versions`);
+    if (versions.length === 0) {
+      fail(`${entryPath}.versions`, `a ${label} history needs at least one version`);
+    }
+    const history = [];
+    versions.forEach((version, position) => {
+      history.push(
+        parseVersion(version, `${entryPath}.versions[${position}]`, identity, position + 1, history),
+      );
+    });
+    histories.set(key, history);
+  });
+  return histories;
+}
+
+// -------------------------------------------------------------------- document loading
+
+/** Build the three append-only histories one canonical commerce document describes. */
+export function loadDocument(document) {
+  const root = asObject(document, 'document');
+  checkKeys(root, 'document', [], ['tariffs', 'policy_rules', 'catalogs']);
+  return {
+    carriers: loadHistories(
+      optional(root, 'tariffs') ?? [], 'document.tariffs',
+      ['carrier_id', 'service_id'], 'tariff', parseTariff,
+    ),
+    policies: loadHistories(
+      optional(root, 'policy_rules') ?? [], 'document.policy_rules',
+      ['rule_id'], 'rule', parseRule,
+    ),
+    catalogs: loadHistories(
+      optional(root, 'catalogs') ?? [], 'document.catalogs',
+      ['catalog_id'], 'catalog', parseCatalogVersion,
+    ),
+  };
+}
+
+function parseTariff(value, path, [carrierId, serviceId], number) {
+  const fields = asObject(value, path);
+  checkKeys(
+    fields, path,
+    ['effective_at', 'dimensional_weight_divisor', 'cost_per_dimensional_kg_minor'],
+    ['minimum_charge_minor', 'fuel_surcharge_permille', 'accessorials'],
+  );
+  const zonesPath = `${path}.cost_per_dimensional_kg_minor`;
+  const costPerDimensionalKgMinor = {};
+  const zones = asObject(fields.cost_per_dimensional_kg_minor, zonesPath);
+  for (const [zone, cost] of Object.entries(zones)) {
+    costPerDimensionalKgMinor[zone] = nonNegative(
+      asInteger(cost, `${zonesPath}[${zone}]`), zonesPath,
+      'cost_per_dimensional_kg_minor entries cannot be negative',
+    );
+  }
+  return {
+    carrierId,
+    serviceId,
+    version: number,
+    effectiveAt: nonNegative(
+      asInteger(fields.effective_at, `${path}.effective_at`),
+      path, 'effective_at cannot be negative',
+    ),
+    dimensionalWeightDivisor: positive(
+      asInteger(fields.dimensional_weight_divisor, `${path}.dimensional_weight_divisor`),
+      path, 'dimensional_weight_divisor must be positive',
+    ),
+    costPerDimensionalKgMinor,
+    minimumChargeMinor: nonNegative(
+      asInteger(optional(fields, 'minimum_charge_minor') ?? 0, `${path}.minimum_charge_minor`),
+      path, 'minimum_charge_minor cannot be negative',
+    ),
+    fuelSurchargePermille: nonNegative(
+      asInteger(optional(fields, 'fuel_surcharge_permille') ?? 0, `${path}.fuel_surcharge_permille`),
+      path, 'fuel_surcharge_permille cannot be negative',
+    ),
+    accessorials: parseAccessorials(optional(fields, 'accessorials') ?? [], `${path}.accessorials`),
+  };
+}
+
+function parseAccessorials(value, path) {
+  const charges = {};
+  asList(value, path).forEach((entry, index) => {
+    const entryPath = `${path}[${index}]`;
+    const fields = asObject(entry, entryPath);
+    checkKeys(fields, entryPath, ['accessorial_id'], ['flat_charge_minor', 'permille_of_base']);
+    const id = asText(fields.accessorial_id, `${entryPath}.accessorial_id`);
+    if (Object.hasOwn(charges, id)) fail(entryPath, `duplicate accessorial_id '${id}'`);
+    const flat = optional(fields, 'flat_charge_minor');
+    const permille = optional(fields, 'permille_of_base');
+    if ((flat === undefined) === (permille === undefined)) {
+      fail(entryPath, 'an accessorial must set exactly one of flat_charge_minor or permille_of_base');
+    }
+    charges[id] = {
+      accessorialId: id,
+      flatChargeMinor: flat === undefined ? null : nonNegative(
+        asInteger(flat, `${entryPath}.flat_charge_minor`),
+        entryPath, 'flat_charge_minor cannot be negative',
+      ),
+      permilleOfBase: permille === undefined ? null : nonNegative(
+        asInteger(permille, `${entryPath}.permille_of_base`),
+        entryPath, 'permille_of_base cannot be negative',
+      ),
+    };
+  });
+  return charges;
+}
+
+function parseRule(value, path, [ruleId], number) {
+  const fields = asObject(value, path);
+  checkKeys(fields, path, ['scope', 'action', 'predicates', 'priority', 'effective_at'], ['reason']);
+  const scope = asEnum(fields.scope, `${path}.scope`, POLICY_SCOPES, 'policy scope');
+  const predicates = parsePredicates(fields.predicates, `${path}.predicates`, scope);
+  if (predicates.length === 0) fail(path, 'a rule must have at least one predicate');
+  return {
+    ruleId,
+    version: number,
+    scope,
+    action: asEnum(fields.action, `${path}.action`, POLICY_ACTIONS, 'policy action'),
+    predicates,
+    priority: asInteger(fields.priority, `${path}.priority`),
+    effectiveAt: nonNegative(
+      asInteger(fields.effective_at, `${path}.effective_at`),
+      path, 'effective_at cannot be negative',
+    ),
+    reason: asText(optional(fields, 'reason') ?? '', `${path}.reason`),
+  };
+}
+
+function parsePredicates(value, path, scope) {
+  return asList(value, path).map((entry, index) => {
+    const entryPath = `${path}[${index}]`;
+    const fields = asObject(entry, entryPath);
+    checkKeys(fields, entryPath, ['scope', 'field', 'operator'], ['value']);
+    if (asEnum(fields.scope, `${entryPath}.scope`, POLICY_SCOPES, 'policy scope') !== scope) {
+      fail(entryPath, "every predicate of a rule must share the rule's own scope");
+    }
+    const operator = asEnum(
+      fields.operator, `${entryPath}.operator`, POLICY_OPERATORS, 'policy operator',
+    );
+    const predicateValue = optional(fields, 'value') ?? null;
+    if (!isUnary(operator) && predicateValue === null) {
+      fail(entryPath, `operator '${operator}' requires a value`);
+    }
+    const field = asText(fields.field, `${entryPath}.field`);
+    if (field === '') fail(entryPath, 'field is required');
+    return { scope, field, operator, value: predicateValue };
+  });
+}
+
+function parseCatalogVersion(value, path, _identity, number, history) {
+  const fields = asObject(value, path);
+  if (Object.hasOwn(fields, 'rollback_to')) return parseRollback(fields, path, number, history);
+  checkKeys(fields, path, ['effective_at', 'published_at', 'snapshot'], ['note']);
+  return {
+    number,
+    snapshot: parseSnapshot(fields.snapshot, `${path}.snapshot`),
+    effectiveAt: nonNegative(
+      asInteger(fields.effective_at, `${path}.effective_at`),
+      path, 'effective_at cannot be negative',
+    ),
+    publishedAt: nonNegative(
+      asInteger(fields.published_at, `${path}.published_at`),
+      path, 'published_at cannot be negative',
+    ),
+    rolledBackFrom: null,
+    note: asText(optional(fields, 'note') ?? '', `${path}.note`),
+  };
+}
+
+/** A rollback is a new, higher-numbered version whose snapshot equals a prior one's. */
+function parseRollback(fields, path, number, history) {
+  checkKeys(fields, path, ['rollback_to', 'published_at'], ['effective_at', 'note']);
+  const toVersion = asInteger(fields.rollback_to, `${path}.rollback_to`);
+  const target = history.find((version) => version.number === toVersion);
+  if (target === undefined) {
+    fail(path, `rollback_to names version ${toVersion}, which is not published yet`);
+  }
+  const publishedAt = asInteger(fields.published_at, `${path}.published_at`);
+  const note = asText(optional(fields, 'note') ?? '', `${path}.note`);
+  return {
+    number,
+    snapshot: target.snapshot,
+    effectiveAt: asInteger(optional(fields, 'effective_at') ?? publishedAt, `${path}.effective_at`),
+    publishedAt,
+    rolledBackFrom: toVersion,
+    note: note === '' ? `rollback to version ${toVersion}` : note,
+  };
+}
+
+function parseSnapshot(value, path) {
+  const fields = asObject(value, path);
+  checkKeys(fields, path, [], ['items', 'cartons', 'pallets', 'exclusions', 'overrides']);
+  const collect = (key, parse) => asList(optional(fields, key) ?? [], `${path}.${key}`)
+    .map((entry, index) => parse(
+      asObject(entry, `${path}.${key}[${index}]`), `${path}.${key}[${index}]`,
+    ));
+
+  const snapshot = {
+    items: collect('items', parseItem),
+    cartons: collect('cartons', parseCarton),
+    pallets: collect('pallets', parsePallet),
+    exclusions: collect('exclusions', parseExclusion),
+    overrides: collect('overrides', parseOverride),
+  };
+  requireUniqueIds(snapshot.items, 'item', path);
+  requireUniqueIds(snapshot.cartons, 'carton', path);
+  requireUniqueIds(snapshot.pallets, 'pallet', path);
+  requireUniqueIds(snapshot.exclusions, 'exclusion', path);
+  requireUniqueIds(snapshot.overrides, 'facility override', path);
+  return snapshot;
+}
+
+function identifier(fields, path, label) {
+  const id = asText(fields.id, `${path}.id`);
+  if (id === '') fail(path, `${label} id is required`);
+  return id;
+}
+
+function parseItem(fields, path) {
+  checkKeys(fields, path, ['id', 'dimensions_mm', 'weight_g'], ['description']);
+  const dimensions = asAxes(fields.dimensions_mm, `${path}.dimensions_mm`, 3);
+  if (dimensions.some((axis) => axis <= 0)) fail(path, 'item dimensions must be positive');
+  return {
+    id: identifier(fields, path, 'item'),
+    dimensionsMm: dimensions,
+    weightG: positive(
+      asInteger(fields.weight_g, `${path}.weight_g`), path, 'item weight must be positive',
+    ),
+    description: asText(optional(fields, 'description') ?? '', `${path}.description`),
+  };
+}
+
+function parseCarton(fields, path) {
+  checkKeys(fields, path, ['id', 'inner_dimensions_mm', 'max_payload_g'], ['cost_minor']);
+  const dimensions = asAxes(fields.inner_dimensions_mm, `${path}.inner_dimensions_mm`, 3);
+  if (dimensions.some((axis) => axis <= 0)) fail(path, 'carton dimensions must be positive');
+  return {
+    id: identifier(fields, path, 'carton'),
+    innerDimensionsMm: dimensions,
+    maxPayloadG: positive(
+      asInteger(fields.max_payload_g, `${path}.max_payload_g`),
+      path, 'carton max_payload_g must be positive',
+    ),
+    costMinor: nonNegative(
+      asInteger(optional(fields, 'cost_minor') ?? 0, `${path}.cost_minor`),
+      path, 'cost_minor cannot be negative',
+    ),
+  };
+}
+
+function parsePallet(fields, path) {
+  checkKeys(fields, path, ['id', 'deck_dimensions_mm', 'max_payload_g'], ['max_stack_height_mm']);
+  const deck = asAxes(fields.deck_dimensions_mm, `${path}.deck_dimensions_mm`, 2);
+  if (deck.some((axis) => axis <= 0)) fail(path, 'pallet dimensions must be positive');
+  const height = optional(fields, 'max_stack_height_mm');
+  return {
+    id: identifier(fields, path, 'pallet'),
+    deckDimensionsMm: deck,
+    maxPayloadG: positive(
+      asInteger(fields.max_payload_g, `${path}.max_payload_g`),
+      path, 'pallet max_payload_g must be positive',
+    ),
+    maxStackHeightMm: height === undefined ? null : positive(
+      asInteger(height, `${path}.max_stack_height_mm`),
+      path, 'max_stack_height_mm must be positive',
+    ),
+  };
+}
+
+function parseExclusion(fields, path) {
+  checkKeys(fields, path, ['id', 'scope', 'subject_id', 'excluded_id'], ['reason']);
+  const subjectId = asText(fields.subject_id, `${path}.subject_id`);
+  const excludedId = asText(fields.excluded_id, `${path}.excluded_id`);
+  if (subjectId === '' || excludedId === '') {
+    fail(path, 'an exclusion rule must reference both a subject and an excluded id');
+  }
+  return {
+    id: identifier(fields, path, 'exclusion'),
+    scope: asEnum(fields.scope, `${path}.scope`, EXCLUSION_SCOPES, 'exclusion scope'),
+    subjectId,
+    excludedId,
+    reason: asText(optional(fields, 'reason') ?? '', `${path}.reason`),
+  };
+}
+
+function parseOverride(fields, path) {
+  checkKeys(fields, path, ['id', 'facility_id', 'entry_id', 'kind', 'override']);
+  const kind = asEnum(fields.kind, `${path}.kind`, OVERRIDE_KINDS, 'override kind');
+  const parse = { item: parseItem, carton: parseCarton, pallet: parsePallet }[kind];
+  const entry = parse(asObject(fields.override, `${path}.override`), `${path}.override`);
+  const facilityId = asText(fields.facility_id, `${path}.facility_id`);
+  const entryId = asText(fields.entry_id, `${path}.entry_id`);
+  if (facilityId === '') fail(path, 'facility_id is required');
+  if (entry.id !== entryId) fail(path, "a facility override's entry_id must match override.id");
+  return { id: identifier(fields, path, 'facility override'), facilityId, entryId, kind, entry };
+}
+
+// --------------------------------------------------------------------------- responses
+
+function ok(key, payload) {
+  return { api_version: API_VERSION, status: 'ok', [key]: payload };
+}
+
+function rejected(code, fields) {
+  return { api_version: API_VERSION, status: 'rejected', error: { code, fields } };
+}
+
+function exactlyOne(request, names) {
+  const present = names.filter((name) => optional(request, name) !== undefined);
+  if (present.length !== 1) fail('request', `expected exactly one of ${JSON.stringify(names)}`);
+  return present[0];
+}
+
+// ------------------------------------------------------------------------------- quote
+
+/** Price one shipment against one pinned or effective-dated tariff version. */
+export function quote(document, request) {
+  const loaded = loadDocument(document);
+  const fields = asObject(request, 'request');
+  checkKeys(
+    fields, 'request',
+    ['carrier_id', 'service_id', 'zone', 'actual_weight_g', 'volume_mm3'],
+    ['tariff_version', 'as_of', 'requested_accessorials'],
+  );
+  const pin = exactlyOne(fields, ['tariff_version', 'as_of']);
+  const carrierId = asText(fields.carrier_id, 'request.carrier_id');
+  const serviceId = asText(fields.service_id, 'request.service_id');
+  const ratingRequest = parseRatingRequest(fields);
+  const identity = { carrier_id: carrierId, service_id: serviceId };
+
+  const resolved = resolveTariff(loaded.carriers, identity, fields, pin);
+  if (resolved.rejection !== undefined) {
+    return rejected(resolved.rejection.code, resolved.rejection.fields);
+  }
+
+  const { tariff } = resolved;
+  const { breakdown, rejection } = rateTariff(tariff, ratingRequest);
+  if (rejection !== undefined) {
+    const where = { ...identity, tariff_version: tariff.version };
+    return rejection.kind === 'zone'
+      ? rejected('unavailable_zone', { ...where, zone: rejection.zone })
+      : rejected('unavailable_accessorial', { ...where, accessorial_ids: rejection.accessorialIds });
+  }
+  return ok('quote', breakdown);
+}
+
+function resolveTariff(carriers, identity, fields, pin) {
+  const history = carriers.get(`${identity.carrier_id}/${identity.service_id}`);
+  if (pin === 'tariff_version') {
+    const version = asInteger(fields.tariff_version, 'request.tariff_version');
+    const tariff = history?.find((candidate) => candidate.version === version);
+    if (tariff === undefined) {
+      return { rejection: { code: 'tariff_not_found', fields: { ...identity, tariff_version: version } } };
+    }
+    return { tariff };
+  }
+  const asOf = asInteger(fields.as_of, 'request.as_of');
+  if (history === undefined) {
+    return { rejection: { code: 'tariff_not_found', fields: identity } };
+  }
+  const tariff = effectiveVersion(history, asOf, (candidate) => candidate.version);
+  if (tariff === null) {
+    return { rejection: { code: 'no_effective_tariff', fields: { ...identity, as_of: asOf } } };
+  }
+  return { tariff };
+}
+
+function parseRatingRequest(fields) {
+  const requestedAccessorials = asList(
+    optional(fields, 'requested_accessorials') ?? [], 'request.requested_accessorials',
+  ).map((entry, index) => asText(entry, `request.requested_accessorials[${index}]`));
+  if (requestedAccessorials.some((id) => id === '')) {
+    fail('request.requested_accessorials', 'accessorial ids must be non-empty');
+  }
+  if (new Set(requestedAccessorials).size !== requestedAccessorials.length) {
+    fail('request.requested_accessorials', 'accessorial ids must be unique');
+  }
+  const zone = asText(fields.zone, 'request.zone');
+  if (zone === '') fail('request.zone', 'zone is required');
+  return {
+    zone,
+    actualWeightG: nonNegative(
+      asInteger(fields.actual_weight_g, 'request.actual_weight_g'),
+      'request.actual_weight_g', 'actual_weight_g cannot be negative',
+    ),
+    volumeMm3: nonNegative(
+      asInteger(fields.volume_mm3, 'request.volume_mm3'),
+      'request.volume_mm3', 'volume_mm3 cannot be negative',
+    ),
+    requestedAccessorials,
+  };
+}
+
+// --------------------------------------------------------------------- evaluate policy
+
+/** Decide one eligibility question against a pinned or effective-dated rule set. */
+export function evaluatePolicy(document, request) {
+  const loaded = loadDocument(document);
+  const fields = asObject(request, 'request');
+  checkKeys(fields, 'request', ['scope', 'context'], ['as_of', 'rule_versions']);
+  const pin = exactlyOne(fields, ['as_of', 'rule_versions']);
+  const scope = asEnum(fields.scope, 'request.scope', POLICY_SCOPES, 'policy scope');
+  const context = asObject(fields.context, 'request.context');
+
+  if (pin === 'as_of') {
+    const asOf = asInteger(fields.as_of, 'request.as_of');
+    const effective = [...loaded.policies.values()]
+      .map((history) => effectiveVersion(history, asOf, (rule) => rule.version))
+      .filter((rule) => rule !== null);
+    return ok('decision', decide(effective, scope, context));
+  }
+  const resolved = resolvePins(loaded.policies, fields.rule_versions);
+  if (resolved.rejection !== undefined) {
+    return rejected(resolved.rejection.code, resolved.rejection.fields);
+  }
+  return ok('decision', decide(resolved.rules, scope, context));
+}
+
+function resolvePins(policies, value) {
+  const pins = asList(value, 'request.rule_versions').map((entry, index) => {
+    const path = `request.rule_versions[${index}]`;
+    const pair = asList(entry, path);
+    if (pair.length !== 2) fail(path, 'expected a [rule_id, version] pair');
+    return [asText(pair[0], `${path}[0]`), asInteger(pair[1], `${path}[1]`)];
+  });
+  if (new Set(pins.map(([ruleId]) => ruleId)).size !== pins.length) {
+    fail('request.rule_versions', 'a policy snapshot cannot pin the same rule id twice');
+  }
+  // Sorted so an explicit snapshot is order-independent, exactly as the reference
+  // implementation orders it before deciding.
+  pins.sort(([leftId, leftVersion], [rightId, rightVersion]) => (
+    leftId === rightId ? leftVersion - rightVersion : compareCodePoints(leftId, rightId)
+  ));
+
+  const rules = [];
+  for (const [ruleId, version] of pins) {
+    const history = policies.get(ruleId);
+    if (history === undefined) {
+      return { rejection: { code: 'policy_rule_not_found', fields: { rule_id: ruleId } } };
+    }
+    const rule = history.find((candidate) => candidate.version === version);
+    if (rule === undefined) {
+      return { rejection: { code: 'policy_version_not_found', fields: { rule_id: ruleId, version } } };
+    }
+    rules.push(rule);
+  }
+  return { rules };
+}
+
+// ---------------------------------------------------------------- catalog version info
+
+/** Report which catalog version a reference resolves to, and what it contains. */
+export function catalogVersionInfo(document, request) {
+  const loaded = loadDocument(document);
+  const fields = asObject(request, 'request');
+  checkKeys(fields, 'request', ['catalog_id', 'resolved_at'], ['version', 'as_of']);
+  const catalogId = asText(fields.catalog_id, 'request.catalog_id');
+  const resolvedAt = asInteger(fields.resolved_at, 'request.resolved_at');
+  const version = optional(fields, 'version') === undefined
+    ? undefined
+    : asInteger(fields.version, 'request.version');
+  const asOf = optional(fields, 'as_of') === undefined
+    ? undefined
+    : asInteger(fields.as_of, 'request.as_of');
+  if (version !== undefined && asOf !== undefined) {
+    fail('request', 'expected at most one of ["as_of","version"]');
+  }
+
+  const history = loaded.catalogs.get(catalogId);
+  if (history === undefined) return rejected('catalog_not_found', { catalog_id: catalogId });
+  const selector = { catalog_id: catalogId };
+  if (version !== undefined) selector.version = version;
+  if (asOf !== undefined) selector.as_of = asOf;
+
+  const resolved = resolveCatalogVersion(history, version, asOf);
+  if (typeof resolved === 'string') return rejected(resolved, selector);
+  return ok('catalog', catalogPayload(catalogId, resolved, resolvedAt));
+}
+
+function resolveCatalogVersion(history, version, asOf) {
+  if (version !== undefined) {
+    return history.find((candidate) => candidate.number === version) ?? 'catalog_version_not_found';
+  }
+  if (asOf === undefined) {
+    return history.length > 1 ? 'ambiguous_catalog_reference' : history[0];
+  }
+  return effectiveVersion(history, asOf, (candidate) => candidate.number)
+    ?? 'no_effective_catalog_version';
+}
+
+function catalogPayload(catalogId, version, resolvedAt) {
+  const { snapshot } = version;
+  // Sorted so no map or insertion ordering can leak into the answer.
+  const ids = (entries) => entries.map((entry) => entry.id).sort(compareCodePoints);
+  return {
+    catalog_id: catalogId,
+    version: version.number,
+    effective_at: version.effectiveAt,
+    published_at: version.publishedAt,
+    resolved_at: resolvedAt,
+    rolled_back_from: version.rolledBackFrom,
+    note: version.note,
+    entry_counts: {
+      items: snapshot.items.length,
+      cartons: snapshot.cartons.length,
+      pallets: snapshot.pallets.length,
+      exclusions: snapshot.exclusions.length,
+      overrides: snapshot.overrides.length,
+    },
+    item_ids: ids(snapshot.items),
+    carton_ids: ids(snapshot.cartons),
+    pallet_ids: ids(snapshot.pallets),
+  };
+}
+
+// ---------------------------------------------------------------------- canonical form
+
+/** The one byte-comparable spelling of a result document: sorted keys, no padding. */
+export function canonicalJson(result) {
+  const sort = (value) => {
+    if (Array.isArray(value)) return value.map(sort);
+    if (value === null || typeof value !== 'object') return value;
+    return Object.fromEntries(
+      Object.keys(value).sort(compareCodePoints).map((key) => [key, sort(value[key])]),
+    );
+  };
+  return JSON.stringify(sort(result));
+}
diff --git a/docs/COMMERCE-API.md b/docs/COMMERCE-API.md
new file mode 100644
index 0000000..6237164
--- /dev/null
+++ b/docs/COMMERCE-API.md
@@ -0,0 +1,392 @@
+# Commercial and control-plane API
+
+The packing engines and the commercial layer around them — carrier rating,
+eligibility/policy evaluation and catalog versioning — are public APIs. This document
+defines the latter contract: three exported
+functions, one canonical input document, one canonical result shape and one closed set
+of rejection codes, identical in all four languages.
+
+**No packing-request or packing-result schema field is added or changed by this API.**
+Both existing wire schemas are untouched. `container.rate_table`
+and `policy` are already public wire fields; what was missing was the
+catalog/versioning layer *around* them and a callable entry point, not a field.
+
+## Design rules
+
+1. **One implementation per language, never two.** Python's export is the workspace
+   modules themselves, relocated into the installable package with the workspace paths
+   kept alive as re-export shims (see [Traceability](#traceability)). PHP, Rust and
+   JavaScript are independent implementations of this contract, held to the same
+   cross-language standard as every other capability in this project (see
+   [Conformance standard](#conformance-standard)).
+2. **Data in, data out.** Every function takes plain JSON-shaped data and returns
+   plain JSON-shaped data. No registry object crosses the API boundary, so the same
+   fixture can drive all four languages over a subprocess boundary — the only way the
+   conformance harness can check that they agree.
+3. **Deterministic, no clock.** Nothing reads wall-clock time. Every "which version
+   applies" question is answered from an explicit `version` pin or an explicit `as_of`
+   value supplied by the caller, so a stored result replays byte-for-byte.
+4. **Exact integers only.** Ticks for length, grams for weight, minor currency units
+   for money, permille for percentage-shaped rates. Every inexact division rounds up.
+   No floats appear anywhere in the input, the arithmetic or the output.
+5. **One ordering: by Unicode code point.** Every sorted list in a result — the catalog
+   id lists, the accessorial ids in an `unavailable_accessorial` rejection — and every
+   deterministic tie-break on an id is ordered by code point, never by a locale
+   collation and never by UTF-16 code unit. The distinction is not academic: by code
+   unit, an emoji sorts *before* a fullwidth Latin A, and by code point it sorts after.
+   `conformance/commerce/fixtures/catalog-unicode-id-ordering.json` and
+   `policy-astral-rule-id-tie-break.json` hold every implementation to this.
+6. **Structured rejections, not silent zeros.** A zone with no rate, an accessorial the
+   tariff does not offer, a catalog version that does not exist — each is a named
+   rejection code with structured fields, never an empty or zero-valued success.
+
+## Exported functions
+
+| Function | Python | PHP | Rust | JavaScript |
+| --- | --- | --- | --- | --- |
+| Quote | `packvium.commerce.quote(document, request)` | `Packvium\Commerce\quote(array $document, array $request)` | `packvium_core::commerce::quote_json(&str)` | `import { commerce } from '@packvium/engine'; commerce.quote(document, request)` |
+| Policy | `packvium.commerce.evaluate_policy(document, request)` | `Packvium\Commerce\evaluatePolicy(...)` | `packvium_core::commerce::evaluate_policy_json(&str)` | `commerce.evaluatePolicy(document, request)` |
+| Catalog | `packvium.commerce.catalog_version_info(document, request)` | `Packvium\Commerce\catalogVersionInfo(...)` | `packvium_core::commerce::catalog_version_info_json(&str)` | `commerce.catalogVersionInfo(document, request)` |
+
+The original API proposal sketches these as `quote(request, catalog_version,
+policy_version)`, `evaluate_policy(request, policy_version)` and
+`catalog_version_info(version)`. The version pins are carried *inside* the request
+object rather than as positional arguments, for one reason: a pin is only meaningful
+against the history it indexes into, so the history (`document`) and the pin
+(`request.tariff_version` / `request.rule_versions` / `request.version`) must arrive
+together or a caller can pin version 3 of a document that has two. The information
+content is identical; the shape makes the invalid combination unrepresentable as two
+independent arguments.
+
+The C ABI adds `packvium_commerce_quote`, `packvium_commerce_evaluate_policy` and
+`packvium_commerce_catalog_version_info`, each `const char* -> char*` over the same
+JSON, freed with the existing `packvium_free_string`. See
+[PUBLIC-API.md](PUBLIC-API.md).
+
+## The commerce document
+
+One object holding the three append-only histories. Every history is a list of
+versions in publication order; **a version's number is its 1-based position in that
+list**, exactly as `CarrierRegistry.publish`, `PolicyRegistry.publish` and
+`CatalogRegistry.publish` already number them. A document therefore cannot express a
+history with a hole or a duplicated version number.
+
+```json
+{
+  "tariffs": [
+    {
+      "carrier_id": "acme",
+      "service_id": "ground",
+      "versions": [
+        {
+          "effective_at": 0,
+          "dimensional_weight_divisor": 5000,
+          "cost_per_dimensional_kg_minor": {"zone-a": 450, "zone-b": 610},
+          "minimum_charge_minor": 900,
+          "fuel_surcharge_permille": 120,
+          "accessorials": [
+            {"accessorial_id": "liftgate", "flat_charge_minor": 250},
+            {"accessorial_id": "residential", "permille_of_base": 75}
+          ]
+        }
+      ]
+    }
+  ],
+  "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, "description": ""}
+            ],
+            "cartons": [
+              {"id": "box-m", "inner_dimensions_mm": [320, 240, 180], "max_payload_g": 15000, "cost_minor": 85}
+            ],
+            "pallets": [
+              {"id": "euro", "deck_dimensions_mm": [1200, 800], "max_payload_g": 1000000,
+               "max_stack_height_mm": 1800}
+            ],
+            "exclusions": [
+              {"id": "x1", "scope": "item_carton", "subject_id": "sku-1",
+               "excluded_id": "box-m", "reason": "hazmat"}
+            ],
+            "overrides": [
+              {"id": "o1", "facility_id": "DC-12", "entry_id": "box-m",
+               "kind": "carton",
+               "override": {"id": "box-m", "inner_dimensions_mm": [300, 240, 180],
+                            "max_payload_g": 14000, "cost_minor": 85}}
+            ]
+          }
+        },
+        {"rollback_to": 1, "published_at": 900, "effective_at": 900, "note": "revert bad correction"}
+      ]
+    }
+  ]
+}
+```
+
+All three top-level keys are optional; a document that only needs to price a shipment
+may carry only `tariffs`. Field-level rules:
+
+- `accessorials` is an ordered **list**, not an object, so no language has to agree
+  about key order; each entry sets exactly one of `flat_charge_minor` or
+  `permille_of_base`. Duplicate `accessorial_id` values are an input error.
+- A catalog version is either a full `snapshot` version or a `rollback_to` version
+  (never both). A rollback publishes a *new*, higher-numbered version whose snapshot
+  equals the referenced one's; history is never rewritten.
+- A facility override names its `kind` (`item` / `carton` / `pallet`) explicitly rather
+  than leaving it to be inferred from which fields the payload happens to carry.
+- An omitted optional field and an explicit JSON `null` mean the same thing: absent.
+  Writing `"minimum_charge_minor": null` is exactly writing nothing.
+- Every integer is exact and, except where a model explicitly allows zero, positive.
+  The per-field bounds are the ones the models already enforce — see
+  CATALOG-VERSIONING.md and POLICY-RULES.md.
+
+### Input errors versus rejections
+
+A malformed document — a missing required key, a negative weight, an unknown policy
+operator, a duplicate id — is an **input error**: `CommerceInputError` in Python,
+`Packvium\Commerce\CommerceInputError` in PHP, `Err(CommerceError::Input)` in Rust, a
+thrown `CommerceInputError` in JavaScript. It is a caller bug, reported the way each
+language reports caller bugs.
+
+A well-formed request the commercial model cannot answer — no tariff effective as of
+that instant, no rate for that zone — is a **rejection**: a successful call returning
+`"status": "rejected"` with a code from the closed set below. This mirrors how the
+packing API already treats an infeasible request: a `PackingResult` with a status, not
+an exception.
+
+## Result shapes
+
+Every result is an object with `api_version` (currently `1`) and `status`
+(`"ok"` or `"rejected"`).
+
+### `quote`
+
+Request:
+
+```json
+{"carrier_id": "acme", "service_id": "ground", "tariff_version": 1,
+ "zone": "zone-a", "actual_weight_g": 1200, "volume_mm3": 6000000,
+ "requested_accessorials": ["liftgate"]}
+```
+
+Exactly one of `tariff_version` (pinned replay) or `as_of` (effective-dated lookup)
+must be present. `requested_accessorials` defaults to `[]` and must be unique.
+
+Success — the fields of `commerce/rating/model.py`'s `RateBreakdown`, one for one:
+
+```json
+{"api_version": 1, "status": "ok",
+ "quote": {"carrier_id": "acme", "service_id": "ground", "tariff_version": 1,
+           "zone": "zone-a", "actual_weight_g": 1200, "dimensional_weight_g": 1200,
+           "billed_weight_g": 1200, "base_charge_minor": 900,
+           "minimum_charge_applied": true, "fuel_surcharge_minor": 108,
+           "accessorial_charges_minor": [["liftgate", 250]], "total_minor": 1258}}
+```
+
+`accessorial_charges_minor` is a list of `[accessorial_id, amount_minor]` pairs in the
+order the request asked for them — the same ordering `RateBreakdown` already records,
+preserved rather than sorted so a caller can line the charges up against the request.
+
+`total_minor` is the identical number `commerce/rating/objective.py`'s
+`CarrierRateSolutionScorer` and `CarrierRateContainerSelector` already rank containers
+and solutions by. That is the point of this function: the price a caller is quoted and
+the price the engine optimised against come from one code path.
+
+### `evaluate_policy`
+
+Request:
+
+```json
+{"scope": "hazmat", "context": {"un_class": "1.4"}, "as_of": 1000}
+```
+
+Exactly one of `as_of` or `rule_versions` (a list of `[rule_id, version]` pairs, each
+rule id at most once) must be present. `rule_versions` is the pinned-replay form and
+resolves through `PolicyRegistry.resolve_versions`, which sorts the pins so the
+snapshot is order-independent.
+
+Success:
+
+```json
+{"api_version": 1, "status": "ok",
+ "decision": {"scope": "hazmat", "allowed": false,
+              "citation": {"rule_id": "no-hazmat-air", "version": 1, "action": "reject",
+                           "priority": 10, "reason": "class 1.4 is not accepted on air services"}}}
+```
+
+`citation` is `null` exactly when nothing matched (the open-by-default ALLOW). A
+`false` `allowed` always carries a citation — the model refuses to construct a
+citation-free rejection.
+
+### `catalog_version_info`
+
+Request:
+
+```json
+{"catalog_id": "dc-12", "version": 2, "resolved_at": 1700}
+```
+
+`resolved_at` is required. At most one of `version` or `as_of`; supplying neither is
+allowed only when the catalog has zero or one published version, and is otherwise the
+`ambiguous_catalog_reference` rejection.
+
+Success — metadata about the version, deliberately *not* the whole snapshot (a caller
+who wants the master data resolves it through the catalog itself; this function
+answers "which version am I looking at and what does it contain"):
+
+```json
+{"api_version": 1, "status": "ok",
+ "catalog": {"catalog_id": "dc-12", "version": 2, "effective_at": 900,
+             "published_at": 900, "resolved_at": 1700, "rolled_back_from": 1,
+             "note": "revert bad correction",
+             "entry_counts": {"items": 1, "cartons": 1, "pallets": 1,
+                              "exclusions": 1, "overrides": 1},
+             "item_ids": ["sku-1"], "carton_ids": ["box-m"], "pallet_ids": ["euro"]}}
+```
+
+`rolled_back_from` is `null` for an ordinary publication. The three id lists are sorted
+ascending by code-point so no language's map or set ordering can leak into the answer.
+
+### Rejections
+
+```json
+{"api_version": 1, "status": "rejected",
+ "error": {"code": "unavailable_zone",
+           "fields": {"carrier_id": "acme", "service_id": "ground",
+                      "tariff_version": 1, "zone": "zone-z"}}}
+```
+
+The closed set of codes, and the workspace error each one corresponds to:
+
+| Code | Raised by | Meaning |
+| --- | --- | --- |
+| `tariff_not_found` | `TariffNotFoundError` | No history for that `(carrier_id, service_id)`, or no such version number |
+| `no_effective_tariff` | `TariffNotFoundError` | A history exists but no version is effective as of `as_of` |
+| `unavailable_zone` | `UnavailableServiceError` | The resolved tariff prices no such zone |
+| `unavailable_accessorial` | `UnavailableServiceError` | The resolved tariff does not offer a requested accessorial |
+| `policy_rule_not_found` | `PolicyRuleNotFoundError` | A pinned `rule_id` has no history |
+| `policy_version_not_found` | `PolicyVersionNotFoundError` | A pinned rule version number does not exist |
+| `catalog_not_found` | `CatalogError` | No catalog with that `catalog_id` in the document |
+| `catalog_version_not_found` | `CatalogVersionNotFoundError` | No such version number, or the catalog has none |
+| `no_effective_catalog_version` | `NoEffectiveCatalogVersionError` | `as_of` predates every version |
+| `ambiguous_catalog_reference` | `AmbiguousCatalogReferenceError` | Neither `version` nor `as_of`, with more than one version published |
+
+`error.fields` carries only structured values — ids, version numbers, the offending
+zone or accessorial id — never a prose message. Human-readable text is a property of
+each language's own exception type and is deliberately excluded from the result
+document, because prose is the one thing four independent implementations cannot be
+held byte-identical on.
+
+`unavailable_accessorial` reports every missing accessorial at once, in a sorted
+`accessorial_ids` list, matching what `rate_tariff` already does.
+
+## Traceability
+
+Every exported behaviour resolves to code that already existed before this epic. No
+function below computes anything itself.
+
+| Exported | Wraps | Now lives at |
+| --- | --- | --- |
+| `quote` | `rate_tariff`, `CarrierRegistry.rate` / `.rate_with_version`, `Tariff`, `AccessorialCharge`, `RateBreakdown`, `RatingRequest` | `packvium/commerce/rating.py`, re-exported from `commerce/rating/model.py` |
+| `evaluate_policy` | `PolicyRegistry.evaluate` / `.resolve_versions`, `decide`, `PolicyRule`, `PolicyPredicate`, `PolicyDecision`, `PolicyCitation` | `packvium/commerce/policy.py`, re-exported from `domain/policy/model.py` |
+| `catalog_version_info` | `CatalogRegistry.publish` / `.rollback` / `.resolve`, `CatalogVersion`, `CatalogSnapshot`, `CatalogReference` | `packvium/commerce/catalog.py`, re-exported from `domain/catalog/model.py` |
+
+The Python relocation is a move, not a copy. `commerce/rating/model.py`,
+`domain/policy/model.py` and `domain/catalog/model.py` remain importable at their
+original paths and re-export the relocated definitions, so every workspace test,
+`integration/product/`, `simulation/` and `recommendations/` import keeps working
+against the exact same objects. There is one definition of `rate_tariff` in the Python
+tree, and the installed wheel contains it. `commerce/rating/objective.py` — the solver
+adapter — is untouched and stays a workspace module: it registers in-process scorer and
+selector objects, which EXTENDING.md explains are deliberately not
+cross-language features.
+
+## Conformance standard
+
+Held to the standard every other capability in this project is held to, per
+TESTING-AND-RELEASE.md:
+
+- **Python and PHP: byte-identical.** Both are ports of one contract; canonical JSON
+  (sorted keys, `,`/`:` separators, no trailing whitespace) of the result document must
+  match exactly.
+- **Rust and JavaScript: valid, and no worse than the floor.** Both are independent
+  implementations. Every result must be accepted by the independent validator, and for
+  `quote` the `total_minor` must equal the fixture's objective floor — a price is a
+  single exact integer, so "no worse than the floor" and "equal" coincide here; there
+  is no room for an alternative-but-equally-good answer the way there is for a
+  placement.
+- **Uniform rejection.** A fixture no engine can price is rejected by all four with the
+  same `error.code` and the same `error.fields`.
+- **Uniform refusal.** A malformed fixture must make all four *fail* rather than answer.
+  This half matters as much as the others: four implementations that agree on every
+  well-formed input can still disagree about what counts as well-formed, and the language
+  that quietly accepts a string where a list belongs is the one that later returns a
+  different answer. Every documented rejection code must be reached by some fixture, and
+  the runner fails if one is not.
+
+
+## Complexity
+
+`h` = versions in one history, `n` = histories, `p` = predicates per rule,
+`e` = entries in a catalog snapshot, `a` = requested accessorials.
+
+| Operation | Time | Space |
+| --- | --- | --- |
+| Load document | `O(total input size)` | `O(total input size)` |
+| `quote` (pinned) | `O(h + a)` | `O(a)` |
+| `quote` (`as_of`) | `O(h + a)` | `O(a)` |
+| `evaluate_policy` (`as_of`) | `O(n * (h + p))` | `O(n)` |
+| `evaluate_policy` (pinned) | `O(k log k + k * (h + p))` for `k` pins | `O(k)` |
+| `catalog_version_info` | `O(h + e log e)` | `O(e)` |
+
+The `e log e` term is sorting the three id lists; every other bound is a linear scan of
+the relevant history. These match the bounds already published for the underlying
+models in ALGORITHMS-AND-COMPLEXITY.md — the wrapper
+adds parsing and serialization, both linear in the payload, and nothing else.
+
+## Limitations
+
+- The document is supplied by the caller. Nothing here fetches, scrapes or embeds any
+  real carrier's published rates; live rate-card ingestion is still out of scope and
+  still tracked in LIMITATIONS-AND-ROADMAP.md.
+- `catalog_version_info` returns metadata and id lists, not the resolved master-data
+  records. Exporting the full snapshot is a larger surface with its own wire-format
+  question and is not part of this epic.
+- Policy evaluation covers the closed `PolicyScope` / `PolicyOperator` vocabulary.
+  An unrecognised scope or operator fails document admission rather than being
+  silently ignored — the guarantee `domain/policy/model.py` already makes.
+- A JSON number must be written without a fractional part. `1` is an integer; `1.0` and
+  `1e3` are not, and Python, PHP and Rust refuse them. JavaScript cannot tell the
+  difference — `JSON.parse` gives the same `Number` for `1` and `1.0` — so this is the
+  one shape where the four implementations cannot be made to agree, and the contract
+  resolves it by requiring callers not to emit it. No fixture uses one.
+- JavaScript refuses, rather than rounds, a quote whose components exceed
+  `Number.MAX_SAFE_INTEGER`. The arithmetic itself runs in `BigInt`, so nothing drifts
+  through a double; what cannot be done is *reporting* a value a JSON number cannot hold
+  exactly. Python has no such ceiling, Rust takes every product in `i128`, and PHP falls
+  back to decimal-string arithmetic. The bound is far above any real tariff — nine
+  quadrillion minor currency units.
diff --git a/docs/GUARANTEES.md b/docs/GUARANTEES.md
index c163f61..e0a8728 100644
--- a/docs/GUARANTEES.md
+++ b/docs/GUARANTEES.md
@@ -48,7 +48,7 @@ silently — if you need them, they belong in your own layer above this library.
 
 ## Status of this release
 
-Version `0.1.0` is an early release. The public API is not yet frozen: field names,
+Version `0.1.1` is an early release. The public API is not yet frozen: field names,
 status codes and the objective vector may change before `1.0.0`. Pin an exact version.
 
 The algorithm complexities documented in `ALGORITHMS-AND-COMPLEXITY.md` are design
diff --git a/docs/PUBLIC-API.md b/docs/PUBLIC-API.md
index 2d38c76..2089bb4 100644
--- a/docs/PUBLIC-API.md
+++ b/docs/PUBLIC-API.md
@@ -357,6 +357,38 @@ details. A structural bound takes precedence over a deadline: an oversized item
 `proven` even if the overall run timed out. Conversely, `time_limit`, `search_exhausted`
 and other unfinished-search outcomes can never carry `proven`.
 
+## Commercial and control-plane API
+
+Three deterministic functions over one canonical JSON document -- a carrier quote, an
+eligibility decision, and catalog version metadata. They are a separate surface from the
+packing API and add no packing-request or packing-result field; the full contract, with
+the document format, every result shape, the closed set of rejection codes, complexity
+and limitations, is [COMMERCE-API.md](COMMERCE-API.md).
+
+| Language | Entry point |
+| --- | --- |
+| Python | `packvium.commerce.quote(document, request)`, `.evaluate_policy(...)`, `.catalog_version_info(...)`, `.canonical_json(result)` |
+| PHP | `Packvium\Commerce\quote(array $document, array $request)`, `evaluatePolicy(...)`, `catalogVersionInfo(...)`, `canonicalJson(...)` |
+| Rust | `packvium_core::commerce::quote_json(&str)`, `evaluate_policy_json(&str)`, `catalog_version_info_json(&str)` |
+| JavaScript | `commerce.quote(document, request)`, `.evaluatePolicy(...)`, `.catalogVersionInfo(...)` on `@packvium/engine`; the same three, async, on `@packvium/browser` |
+| C ABI | `packvium_commerce_quote(call)`, `packvium_commerce_evaluate_policy(call)`, `packvium_commerce_catalog_version_info(call)` |
+
+The Rust, C ABI and WASM entry points take one JSON string, `{"document": ..., "request":
+...}`, and return the result document as a string. Each C ABI function follows the same
+pointer contract as `packvium_solve_json`: a valid, immutable, NUL-terminated UTF-8
+input, and an owned result string the caller releases exactly once with
+`packvium_free_string`. `@packvium/engine` selects the native addon when it is installed
+and the deterministic JavaScript implementation otherwise, the same way `pack` does;
+`commerce.backend()` reports which answered.
+
+Two kinds of failure, and they are not interchangeable. A malformed document or request
+is a caller bug and is raised the way each language raises one (`CommerceInputError`,
+`Packvium\Commerce\CommerceInputException`, `Err(CommerceInputError)`, a thrown
+`CommerceInputError`). A well-formed request the commercial model cannot answer -- no
+tariff effective at that instant, no rate for that zone -- is a successful call returning
+`"status": "rejected"` with a code from a closed set, exactly as an infeasible packing
+request returns a result with a status rather than raising.
+
 ## JSON API
 
 Python, PHP, Rust and the JavaScript fallback accept the same top-level keys: `units`,
diff --git a/docs/README.md b/docs/README.md
index 788b3fe..51a2866 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,4 +4,5 @@
 | --- | --- |
 | [GUARANTEES.md](GUARANTEES.md) | What the library promises and what it explicitly does not. |
 | [PUBLIC-API.md](PUBLIC-API.md) | Inputs, outputs and status semantics. |
+| [COMMERCE-API.md](COMMERCE-API.md) | Carrier rating, policy evaluation and catalog-version contracts. |
 | [UNITS-AND-NUMERICS.md](UNITS-AND-NUMERICS.md) | Exact fixed-point units and rounding. |
diff --git a/examples/basic.mjs b/examples/basic.mjs
new file mode 100644
index 0000000..3b3f6f9
--- /dev/null
+++ b/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}`);
+  }
+}
diff --git a/examples/commerce.mjs b/examples/commerce.mjs
new file mode 100644
index 0000000..3aaa73c
--- /dev/null
+++ b/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));
diff --git a/fallback.js b/fallback.js
index 58967b3..198ebfc 100644
--- a/fallback.js
+++ b/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
           }
diff --git a/index.d.ts b/index.d.ts
index 7e9c8d7..9c16ed8 100644
--- a/index.d.ts
+++ b/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;
+};
diff --git a/index.js b/index.js
index aef0c0b..ab2b166 100644
--- a/index.js
+++ b/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.1-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);
+  }
+}
diff --git a/package.json b/package.json
index 67bed53..b08f791 100644
--- a/package.json
+++ b/package.json
@@ -1,14 +1,14 @@
 {
   "name":"@packvium/engine",
-  "version":"0.1.0",
+  "version":"0.1.1",
   "description":"Native-first 3D cartonization with deterministic JS fallback",
   "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.1"},
   "scripts":{
     "test":"node --test \"test/*.test.mjs\"",
     "test:legacy":"node test/legacy-conformance.mjs"
diff --git a/policy.js b/policy.js
new file mode 100644
index 0000000..703453d
--- /dev/null
+++ b/policy.js
@@ -0,0 +1,226 @@
+/**
+ * Versioned eligibility rules, compiled into the checks the packer already runs.
+ *
+ * See docs/POLICY-RULES.md for the contract and the reasoning behind its shape. The
+ * short version: rules travel in the request as data because an engine is driven over
+ * JSON as a subprocess, so a rule registered inside one process has no wire
+ * representation and nothing can check that four engines agree about it.
+ *
+ * Deliberately not a predicate language. `eligible_container_tags`, `incompatible_tags`
+ * and `tag_limits` already express the predicates in every engine, so each rule form
+ * here compiles to a check the packer already performs. What a rule adds is only what
+ * tags cannot carry: identity, effective dating, priority, and the shipment-scoped facts
+ * a request had nowhere to put.
+ *
+ * This module is package-internal: package.json exports only the root entry point.
+ */
+
+// The shipment-scoped facts a rule may select on. Properties of the shipment rather
+// than of any item or container, which is why the request had nowhere to put them.
+const SHIPMENT_FACTS = ['facility', 'customer', 'carrier', 'service'];
+
+// Wire name -> the keys the form requires, in the order they are read. Exactly one may
+// appear on a rule: a rule naming two forms would have no single meaning for a citation.
+const FORMS = {
+  separate_tags: ['tag', 'from_tag'],
+  require_container_tag: ['item_tag', 'container_tag'],
+  limit_tag_per_container: ['tag', 'max'],
+};
+
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const isPlainObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+// The detail strings are part of the cross-language contract, and every other engine
+// renders a tag the way its own language quotes a short string literal. Single quotes
+// are what those agree on; a tag is a request-supplied string, so it is escaped here
+// rather than interpolated raw.
+const quoted = tag => `'${tag.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+
+/**
+ * A rule set this engine cannot honour exactly as written.
+ *
+ * Structured rather than skipped: a rule silently dropped for being malformed would let
+ * a request pack in a way its own policy forbids, which is the failure the whole
+ * contract exists to prevent.
+ */
+export class PolicyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'PolicyError';
+    this.code = 'policy_error';
+  }
+}
+
+function integer(value, where, minimum) {
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new PolicyError(`${where} must be an integer >= ${minimum}`);
+  }
+  return value;
+}
+
+/**
+ * Declared facts, or the absence of one. A fact nobody declared is not a wildcard: a
+ * rule naming it simply never participates, so an unstated facility cannot silently
+ * match a rule written for a specific one.
+ */
+function shipmentContext(raw, where) {
+  const context = {};
+  for (const fact of SHIPMENT_FACTS) context[fact] = null;
+  if (raw == null) return context;
+  if (!isPlainObject(raw)) throw new PolicyError(`${where} must be an object`);
+  const unknown = Object.keys(raw).filter(key => !SHIPMENT_FACTS.includes(key)).sort();
+  if (unknown.length) throw new PolicyError(`${where} names unknown shipment facts: ${unknown.join(', ')}`);
+  for (const [name, value] of Object.entries(raw)) {
+    if (typeof value !== 'string' || !value) throw new PolicyError(`${where}.${name} must be a non-empty string`);
+    context[name] = value;
+  }
+  return context;
+}
+
+/** Whether every fact this selector names equals the shipment's own. */
+const satisfiedBy = (selector, shipment) =>
+  SHIPMENT_FACTS.every(fact => selector[fact] === null || selector[fact] === shipment[fact]);
+
+function parseForm(name, raw, where) {
+  if (!isPlainObject(raw)) throw new PolicyError(`${where} must be an object`);
+  const keys = FORMS[name];
+  const unknown = Object.keys(raw).filter(key => !keys.includes(key)).sort();
+  if (unknown.length) throw new PolicyError(`${where} has unknown keys: ${unknown.join(', ')}`);
+  const missing = keys.filter(key => !hasOwn(raw, key));
+  if (missing.length) throw new PolicyError(`${where} is missing ${missing.join(', ')}`);
+  const form = {kind: name};
+  for (const key of keys) {
+    if (key === 'max') { form.max = integer(raw.max, `${where}.max`, 0); continue }
+    if (typeof raw[key] !== 'string' || !raw[key]) throw new PolicyError(`${where}.${key} must be a non-empty string`);
+    form[key] = raw[key];
+  }
+  return form;
+}
+
+function parseRule(raw, index) {
+  const where = `policy.rules[${index}]`;
+  if (!isPlainObject(raw)) throw new PolicyError(`${where} must be an object`);
+  const named = Object.keys(FORMS).filter(name => hasOwn(raw, name));
+  if (named.length !== 1) {
+    throw new PolicyError(
+      `${where} must name exactly one rule form (${Object.keys(FORMS).sort().join(', ')}), not ${named.length}`);
+  }
+  if (typeof raw.id !== 'string' || !raw.id) throw new PolicyError(`${where}.id must be a non-empty string`);
+  const version = integer(raw.version, `${where}.version`, 1);
+  return {
+    id: raw.id,
+    version,
+    citation: `${raw.id}@${version}`,
+    effective_at: integer(raw.effective_at, `${where}.effective_at`, 0),
+    priority: integer(raw.priority, `${where}.priority`, 0),
+    applies_to: shipmentContext(raw.applies_to, `${where}.applies_to`),
+    form: parseForm(named[0], raw[named[0]], `${where}.${named[0]}`),
+  };
+}
+
+/**
+ * Resolution, fixed by the contract and identical in every engine — or the same request
+ * packs differently depending on which one answered it.
+ */
+function resolve(rules, asOf, shipment) {
+  const participating = rules.filter(
+    rule => rule.effective_at <= asOf && satisfiedBy(rule.applies_to, shipment));
+  // Append-only per id: among participating versions of one id the highest
+  // `effective_at` wins, ties broken by the highest `version`. The same resolution the
+  // catalog registry already uses for `as_of` lookups, deliberately, so a reader learns
+  // one rule and not two.
+  const latest = new Map();
+  for (const rule of participating) {
+    const current = latest.get(rule.id);
+    if (current === undefined || rule.effective_at > current.effective_at
+      || (rule.effective_at === current.effective_at && rule.version > current.version)) {
+      latest.set(rule.id, rule);
+    }
+  }
+  // Citation order, not evaluation order: the first rule that rejects a candidate is the
+  // one cited, so sorting here is what makes the citation deterministic. Ties go to the
+  // lexicographically smallest id -- never to insertion order, which would make the
+  // citation depend on the order the caller happened to write.
+  return [...latest.values()].sort((a, b) => b.priority - a.priority || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/** The rules that participate in one request, already resolved and ordered. */
+export function parsePolicy(raw) {
+  if (raw == null) return [];
+  if (!isPlainObject(raw)) throw new PolicyError('policy must be an object');
+  const unknown = Object.keys(raw).filter(key => !['as_of', 'shipment', 'rules'].includes(key)).sort();
+  if (unknown.length) throw new PolicyError(`policy has unknown keys: ${unknown.join(', ')}`);
+  const declared = raw.rules ?? [];
+  if (!Array.isArray(declared)) throw new PolicyError('policy.rules must be an array');
+  if (!declared.length) return [];
+  // No default: a guessed instant silently activates or hides a restriction, and reading
+  // a clock here would make one request pack differently on different days.
+  if (!hasOwn(raw, 'as_of')) throw new PolicyError('policy.as_of is required whenever policy.rules is non-empty');
+  const asOf = integer(raw.as_of, 'policy.as_of', 0);
+  const shipment = shipmentContext(raw.shipment, 'policy.shipment');
+  return resolve(declared.map(parseRule), asOf, shipment);
+}
+
+/**
+ * Whether every rule permits `itemTags` in a container tagged `containerTags` that
+ * already holds `presentTags`, and the citation of the first that does not.
+ *
+ * `O(m + r)` for `m` placements already in the container and `r` resolved rules: one
+ * pass collecting the tags present, then one pass over the rules. The same bound class
+ * as the tag-count check it compiles onto, so the published complexity bounds are
+ * unchanged. Rules arrive in citation order, so the first rejection is already the one
+ * the contract says to cite.
+ */
+export function policyRejection(rules, itemTags, containerTags, presentTags) {
+  for (const rule of rules) {
+    const form = rule.form;
+    if (form.kind === 'require_container_tag') {
+      if (itemTags.includes(form.item_tag) && !containerTags.includes(form.container_tag)) {
+        return `${rule.citation}: requires a container tagged ${quoted(form.container_tag)}`;
+      }
+    } else if (form.kind === 'separate_tags') {
+      if (itemTags.includes(form.tag) && presentTags.get(form.from_tag)) {
+        return `${rule.citation}: ${quoted(form.tag)} may not share a container with ${quoted(form.from_tag)}`;
+      }
+      if (itemTags.includes(form.from_tag) && presentTags.get(form.tag)) {
+        return `${rule.citation}: ${quoted(form.from_tag)} may not share a container with ${quoted(form.tag)}`;
+      }
+    } else if (itemTags.includes(form.tag) && (presentTags.get(form.tag) ?? 0) >= form.max) {
+      return `${rule.citation}: at most ${form.max} item(s) tagged ${quoted(form.tag)} per container`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The rule that rules an item out of every offered container, if one does.
+ *
+ * Only `require_container_tag` can be answered here, and that is not a gap. It is a
+ * statement about the request alone -- this item carries the tag, no offered container
+ * carries the one it requires -- so it holds however the search goes. Segregation and
+ * per-container caps depend on what else was packed, so an item they leave behind was
+ * left behind by the search, and reporting that as proven would claim more than the
+ * engine knows.
+ *
+ * `O(r * c)` for `r` rules and `c` container templates, once per unpacked item rather
+ * than per candidate.
+ */
+export function provesUnplaceable(rules, itemTags, templates) {
+  for (const rule of rules) {
+    const form = rule.form;
+    if (form.kind !== 'require_container_tag' || !itemTags.includes(form.item_tag)) continue;
+    if (!templates.some(template => (template.tags ?? []).includes(form.container_tag))) {
+      return `${rule.citation}: requires a container tagged ${quoted(form.container_tag)}, `
+        + 'which none of the containers offered carries';
+    }
+  }
+  return null;
+}
+
+/** Tag occurrence counts across placements, for the two forms that need them. */
+export function tagOccurrences(placements) {
+  const counts = new Map();
+  for (const placement of placements) {
+    for (const tag of placement.item.tags) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+  }
+  return counts;
+}
diff --git a/test/commerce-edge-cases.test.mjs b/test/commerce-edge-cases.test.mjs
new file mode 100644
index 0000000..2906a5a
--- /dev/null
+++ b/test/commerce-edge-cases.test.mjs
@@ -0,0 +1,303 @@
+/**
+ * Every way to hand the JavaScript commerce API something it should refuse, plus the
+ * few legal inputs that look like they should be refused and are not.
+ *
+ * The shared fixtures in `commerce.test.mjs` prove this implementation agrees with the
+ * other three. This file covers what a shared fixture cannot reach from outside:
+ * JavaScript's own hazards. A `Number` cannot hold every exact integer the other three
+ * can; a string and an object are both iterable where a list belongs; `1` and `1.0` are
+ * the same value; and the default string sort is by UTF-16 code unit, not code point —
+ * each one a place where this port could silently answer differently from the others.
+ */
+
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { compareCodePoints } from '../commerce-model.js';
+import {
+  CommerceInputError,
+  canonicalJson,
+  catalogVersionInfo,
+  evaluatePolicy,
+  loadDocument,
+  quote,
+} from '../commerce.js';
+
+const TARIFF = {
+  effective_at: 0,
+  dimensional_weight_divisor: 5000,
+  cost_per_dimensional_kg_minor: { 'zone-a': 450 },
+  minimum_charge_minor: 900,
+  fuel_surcharge_permille: 120,
+  accessorials: [{ accessorial_id: 'liftgate', flat_charge_minor: 250 }],
+};
+
+function tariffDocument(overrides = {}) {
+  return {
+    tariffs: [{
+      carrier_id: 'acme',
+      service_id: 'ground',
+      versions: [{ ...TARIFF, ...overrides }],
+    }],
+  };
+}
+
+function catalogDocument(...versions) {
+  return { catalogs: [{ catalog_id: 'c', versions }] };
+}
+
+function policyDocument(overrides = {}) {
+  return {
+    policy_rules: [{
+      rule_id: 'r',
+      versions: [{
+        scope: 'hazmat',
+        action: 'reject',
+        priority: 1,
+        effective_at: 0,
+        predicates: [{ scope: 'hazmat', field: 'un_class', operator: 'equals', value: '1.4' }],
+        ...overrides,
+      }],
+    }],
+  };
+}
+
+function shipment(overrides = {}) {
+  const request = {
+    carrier_id: 'acme',
+    service_id: 'ground',
+    tariff_version: 1,
+    zone: 'zone-a',
+    actual_weight_g: 1200,
+    volume_mm3: 6000000,
+    ...overrides,
+  };
+  return Object.fromEntries(Object.entries(request).filter(([, value]) => value !== null));
+}
+
+function refuses(run, fragment) {
+  assert.throws(run, (error) => {
+    assert.ok(error instanceof CommerceInputError, `expected a CommerceInputError, got ${error}`);
+    assert.match(error.message, fragment);
+    return true;
+  });
+}
+
+// ------------------------------------------------------------------- the number problem
+
+test('an integer beyond the exact range is refused, never silently rounded', () => {
+  const document = tariffDocument({
+    dimensional_weight_divisor: 1,
+    cost_per_dimensional_kg_minor: { 'zone-a': 1_000_000 },
+    minimum_charge_minor: 0,
+    fuel_surcharge_permille: 0,
+    accessorials: [],
+  });
+
+  // 10^15 grams at 10^6 minor units per kilogram is 10^18, well past 2^53.
+  refuses(
+    () => quote(document, shipment({ actual_weight_g: 0, volume_mm3: 10 ** 15 })),
+    /outside JavaScript's exact integer range/,
+  );
+});
+
+test('the largest exactly representable quote is still answered', () => {
+  const document = tariffDocument({
+    dimensional_weight_divisor: 1,
+    cost_per_dimensional_kg_minor: { 'zone-a': 1000 },
+    minimum_charge_minor: 0,
+    fuel_surcharge_permille: 0,
+    accessorials: [],
+  });
+
+  const result = quote(document, shipment({ actual_weight_g: 0, volume_mm3: 9_007_199_254_740 }));
+
+  assert.equal(result.quote.total_minor, 9_007_199_254_740);
+  assert.ok(Number.isSafeInteger(result.quote.total_minor));
+});
+
+// --------------------------------------------------------------------------- code points
+
+test('code-point ordering matches the other implementations, not UTF-16 order', () => {
+  const ids = ['z', '\u{1F600}', 'Ａ'];
+
+  assert.deepEqual([...ids].sort(compareCodePoints), ['z', 'Ａ', '\u{1F600}']);
+  assert.notDeepEqual([...ids].sort(), [...ids].sort(compareCodePoints));
+});
+
+test('code-point ordering falls back to length for a shared prefix', () => {
+  assert.equal(compareCodePoints('ab', 'ab'), 0);
+  assert.equal(compareCodePoints('ab', 'abc'), -1);
+  assert.equal(compareCodePoints('abc', 'ab'), 1);
+});
+
+test('catalog id lists come back in code-point order', () => {
+  const entry = (id) => ({ id, dimensions_mm: [1, 1, 1], weight_g: 1 });
+  const document = catalogDocument({
+    effective_at: 0,
+    published_at: 0,
+    snapshot: { items: [entry('\u{1F600}'), entry('Ａ'), entry('z')] },
+  });
+
+  const result = catalogVersionInfo(document, { catalog_id: 'c', resolved_at: 1 });
+
+  assert.deepEqual(result.catalog.item_ids, ['z', 'Ａ', '\u{1F600}']);
+});
+
+test('a pinned policy snapshot is ordered by code point too', () => {
+  const rule = (id) => ({
+    rule_id: id,
+    versions: [{
+      scope: 'carrier', action: 'reject', priority: 1, effective_at: 0, reason: id,
+      predicates: [{ scope: 'carrier', field: 'f', operator: 'exists' }],
+    }],
+  });
+  const document = { policy_rules: [rule('\u{1F600}'), rule('Ａ')] };
+  const request = {
+    scope: 'carrier',
+    context: { f: 1 },
+    rule_versions: [['Ａ', 1], ['\u{1F600}', 1]],
+  };
+
+  const forward = evaluatePolicy(document, request);
+  const reversed = evaluatePolicy(document, {
+    ...request, rule_versions: [...request.rule_versions].reverse(),
+  });
+
+  assert.equal(canonicalJson(forward), canonicalJson(reversed));
+  assert.equal(forward.decision.citation.rule_id, 'Ａ');
+});
+
+// --------------------------------------------------------------------- malformed documents
+
+test('a document that is not an object is refused', () => {
+  for (const document of [null, [], 'x', 7, true]) {
+    refuses(() => loadDocument(document), /document: expected an object/);
+  }
+});
+
+test('a nested value that is not an object is refused', () => {
+  refuses(
+    () => loadDocument({ tariffs: [{ carrier_id: 'a', service_id: 'g', versions: ['nope'] }] }),
+    /expected an object/,
+  );
+});
+
+test('a history with no versions is refused', () => {
+  for (const document of [
+    { tariffs: [{ carrier_id: 'a', service_id: 'g', versions: [] }] },
+    { policy_rules: [{ rule_id: 'r', versions: [] }] },
+    { catalogs: [{ catalog_id: 'c', versions: [] }] },
+  ]) {
+    refuses(() => loadDocument(document), /at least one version/);
+  }
+});
+
+test('an accessorial must set exactly one kind of charge', () => {
+  for (const accessorial of [
+    { accessorial_id: 'x' },
+    { accessorial_id: 'x', flat_charge_minor: 1, permille_of_base: 1 },
+  ]) {
+    refuses(() => loadDocument(tariffDocument({ accessorials: [accessorial] })), /exactly one/);
+  }
+});
+
+test('a binary predicate without a value is refused', () => {
+  refuses(
+    () => loadDocument(policyDocument({
+      predicates: [{ scope: 'hazmat', field: 'f', operator: 'equals' }],
+    })),
+    /requires a value/,
+  );
+});
+
+test('an exclusion rule needs both ends', () => {
+  refuses(
+    () => loadDocument(catalogDocument({
+      effective_at: 0,
+      published_at: 0,
+      snapshot: {
+        exclusions: [{ id: 'x', scope: 'item_carton', subject_id: 'a', excluded_id: '' }],
+      },
+    })),
+    /must reference both/,
+  );
+});
+
+test('a duplicate id inside one snapshot is refused', () => {
+  const entry = { id: 'same', dimensions_mm: [1, 1, 1], weight_g: 1 };
+
+  refuses(
+    () => loadDocument(catalogDocument({
+      effective_at: 0, published_at: 0, snapshot: { items: [entry, entry] },
+    })),
+    /duplicate item ids/,
+  );
+});
+
+// ---------------------------------------------------------------------- malformed requests
+
+test('an as_of quote against a carrier with no history is not found', () => {
+  const result = quote(tariffDocument(), shipment({
+    carrier_id: 'ghost', tariff_version: null, as_of: 0,
+  }));
+
+  assert.deepEqual(result.error, {
+    code: 'tariff_not_found', fields: { carrier_id: 'ghost', service_id: 'ground' },
+  });
+});
+
+test('an empty accessorial id is refused', () => {
+  refuses(
+    () => quote(tariffDocument(), shipment({ requested_accessorials: [''] })),
+    /non-empty/,
+  );
+});
+
+test('a catalog request may pin a version or an instant, never both', () => {
+  const document = catalogDocument({ effective_at: 0, published_at: 0, snapshot: {} });
+
+  refuses(
+    () => catalogVersionInfo(document, {
+      catalog_id: 'c', resolved_at: 1, version: 1, as_of: 1,
+    }),
+    /at most one/,
+  );
+});
+
+// ------------------------------------------------------------ legal but easily mishandled
+
+test('a value of a type the predicate does not compare simply does not match', () => {
+  const document = policyDocument();
+  const result = evaluatePolicy(document, {
+    scope: 'hazmat', context: { un_class: { nested: true } }, as_of: 0,
+  });
+
+  assert.equal(result.decision.allowed, true);
+});
+
+test('an in predicate over a non-list, non-string value matches nothing', () => {
+  const document = policyDocument({
+    predicates: [{ scope: 'hazmat', field: 'f', operator: 'in', value: 7 }],
+  });
+
+  const result = evaluatePolicy(document, { scope: 'hazmat', context: { f: 7 }, as_of: 0 });
+
+  assert.equal(result.decision.allowed, true);
+});
+
+test('an explicitly null optional field means the same as an omitted one', () => {
+  const document = tariffDocument({
+    minimum_charge_minor: null, fuel_surcharge_permille: null, accessorials: null,
+  });
+
+  const result = quote(document, shipment());
+
+  assert.equal(result.quote.minimum_charge_applied, false);
+  assert.equal(result.quote.fuel_surcharge_minor, 0);
+  assert.deepEqual(result.quote.accessorial_charges_minor, []);
+});
+
+test('canonical output leaves non-ASCII and slashes unescaped', () => {
+  assert.equal(canonicalJson({ note: 'zóna/1 🙂' }), '{"note":"zóna/1 🙂"}');
+});
diff --git a/test/commerce-native-dispatch.test.mjs b/test/commerce-native-dispatch.test.mjs
new file mode 100644
index 0000000..56f26c8
--- /dev/null
+++ b/test/commerce-native-dispatch.test.mjs
@@ -0,0 +1,157 @@
+/**
+ * The native commerce dispatch inside `index.js`.
+ *
+ * `commerce.test.mjs` proves the real Rust addon and the JavaScript fallback agree, but
+ * it loads the addon itself, by its in-workspace build path. The package's own probe
+ * list is `['./packvium-native.node', '@packvium/native']`, and neither resolves in this
+ * workspace -- so `viaNative`, the branch every installed user with the addon takes, was
+ * never executed by any test or measured by any coverage run.
+ *
+ * This supplies a stub at the specifier the package actually probes. `index.js` captures
+ * the module object once and reads each entry point off it per call, so one import is
+ * enough: every case below reshapes the same stub rather than reloading the package.
+ * That matters for more than tidiness -- importing `index.js` twice under different URLs
+ * puts two records for one file into the coverage report, which the coverage gate
+ * refuses as untrustworthy.
+ *
+ * No file is written, and the interception is removed as soon as the import completes,
+ * so nothing here can leak into another suite -- or, worse, into a published package
+ * that then believes it has a native backend.
+ */
+
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import Module from 'node:module';
+
+/** Reshaped per case; `index.js` reads its entry points at call time, not at load time. */
+const stub = {};
+
+const previousLoad = Module._load;
+Module._load = function loadWithStubbedNativeBackend(request, parent, isMain) {
+  if (request === '@packvium/native') return stub;
+  return previousLoad.call(this, request, parent, isMain);
+};
+const engine = await import('../index.js');
+Module._load = previousLoad;
+
+const DOCUMENT = { tariffs: [] };
+const REQUEST = { marker: 'probe' };
+
+/** @param {Record<string, unknown>} entries what this case's addon exports */
+function addon(entries) {
+  for (const key of Object.keys(stub)) delete stub[key];
+  Object.assign(stub, entries);
+}
+
+test('each commerce function reaches its own native entry point', () => {
+  const seen = {};
+  const entry = (name) => (json) => {
+    seen[name] = JSON.parse(json);
+    return JSON.stringify({ entry: name });
+  };
+  addon({
+    commerceQuoteJson: entry('commerceQuoteJson'),
+    commerceEvaluatePolicyJson: entry('commerceEvaluatePolicyJson'),
+    commerceCatalogVersionInfoJson: entry('commerceCatalogVersionInfoJson'),
+  });
+
+  assert.equal(engine.commerce.backend(), 'rust', 'a loadable addon must be reported as the backend');
+
+  for (const [method, name] of [
+    ['quote', 'commerceQuoteJson'],
+    ['evaluatePolicy', 'commerceEvaluatePolicyJson'],
+    ['catalogVersionInfo', 'commerceCatalogVersionInfoJson'],
+  ]) {
+    assert.deepEqual(engine.commerce[method](DOCUMENT, REQUEST), { entry: name });
+    // One `{document, request}` envelope, not two arguments and not a flattened object.
+    assert.deepEqual(seen[name], { document: DOCUMENT, request: REQUEST });
+  }
+});
+
+test('a native failure surfaces as the same error the fallback raises', () => {
+  addon({ commerceQuoteJson: () => { throw new Error('request.zone: expected a string'); } });
+
+  assert.throws(
+    () => engine.commerce.quote(DOCUMENT, REQUEST),
+    (error) => error instanceof engine.CommerceInputError
+      && error.message === 'request.zone: expected a string',
+    'a caller must not have to know which backend answered in order to catch the failure',
+  );
+});
+
+test('an addon that answers with something other than JSON is not silently accepted', () => {
+  addon({ commerceQuoteJson: () => '{ this is not JSON' });
+
+  assert.throws(() => engine.commerce.quote(DOCUMENT, REQUEST), engine.CommerceInputError);
+});
+
+test('an addon carrying only some of the three functions falls back for the rest', () => {
+  addon({ commerceQuoteJson: () => JSON.stringify({ entry: 'native' }) });
+
+  assert.deepEqual(engine.commerce.quote(DOCUMENT, REQUEST), { entry: 'native' });
+
+  // No native `commerceEvaluatePolicyJson`, so this must reach the JavaScript fallback
+  // and be refused there for the same reason the fallback always refuses it.
+  assert.throws(
+    () => engine.commerce.evaluatePolicy(DOCUMENT, REQUEST),
+    engine.CommerceInputError,
+    'a partial addon must not make an operation disappear',
+  );
+});
+
+test('an addon with no commerce surface at all leaves the package on the fallback', () => {
+  addon({ packJson: (input) => input });
+
+  assert.equal(engine.commerce.backend(), 'javascript');
+  assert.equal(engine.backend(), 'rust', 'packing still uses the addon it does carry');
+});
+
+/**
+ * `rebalanceWeight` is the one other native dispatch on this entry point, and it was
+ * unreachable for the same reason. Covered here rather than in its own file because the
+ * stub is what makes it reachable, and a second module instance is what the coverage
+ * gate refuses.
+ */
+test('rebalanceWeight routes to the addon with its arguments already serialised', () => {
+  let seen = null;
+  addon({
+    rebalanceJson: (request, result, maxMoves) => {
+      seen = { request, result, maxMoves };
+      return JSON.stringify({ moves: [] });
+    },
+  });
+
+  const answer = engine.rebalanceWeight({ id: 'r' }, { id: 's' }, { maxMoves: 3 });
+
+  assert.deepEqual(answer, { moves: [] });
+  assert.deepEqual(seen, { request: '{"id":"r"}', result: '{"id":"s"}', maxMoves: 3 });
+});
+
+test('rebalanceWeight falls back when the addon does not carry it', () => {
+  addon({});
+  const side = { length: '100', width: '100', height: '100' };
+  const request = {
+    units: { length: 'mm' },
+    items: [{ id: 'a', dimensions: side }, { id: 'b', dimensions: side }],
+    containers: [{ id: 'box', inner_dimensions: { length: '300', width: '100', height: '100' } }],
+  };
+
+  const balanced = engine.rebalanceWeight(request, engine.pack(request), { maxMoves: 0 });
+
+  assert.deepEqual(balanced.moves, [], 'a zero-move budget can only produce no moves');
+  assert.equal(balanced.containers.length, 1);
+});
+
+test('an out-of-range maxMoves is refused before either backend is consulted', () => {
+  let called = false;
+  addon({ rebalanceJson: () => { called = true; return '{}'; } });
+
+  for (const maxMoves of [-1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1]) {
+    assert.throws(
+      () => engine.rebalanceWeight({}, {}, { maxMoves }),
+      RangeError,
+      `expected ${maxMoves} to be refused`,
+    );
+  }
+  assert.equal(called, false, 'the guard must run before the addon is called');
+});
diff --git a/test/commerce.test.mjs b/test/commerce.test.mjs
new file mode 100644
index 0000000..81b4f36
--- /dev/null
+++ b/test/commerce.test.mjs
@@ -0,0 +1,202 @@
+/**
+ * The exported commercial and control-plane API.
+ *
+ * JavaScript is an independent implementation of the contract, so it is held to
+ * producing a *valid* result that meets each shared fixture's objective floor. For a
+ * quote that floor is an exact integer price, so "no worse than the floor" and "equal
+ * to it" coincide: the fixture half of this suite compares against the committed golden
+ * documents, and the rejection half checks that every documented code is reachable and
+ * carries only structured fields.
+ *
+ * The shared fixtures live in the surrounding workspace; a published copy of this
+ * package does not carry them, so that half skips rather than fails when they are gone.
+ */
+
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+import { commerce } from '../index.js';
+import { CommerceInputError, canonicalJson, quote } from '../commerce.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SHARED = path.resolve(HERE, '../../../../conformance/commerce');
+const hasFixtures = fs.existsSync(path.join(SHARED, 'fixtures'));
+
+const cases = hasFixtures
+  ? fs.readdirSync(path.join(SHARED, 'fixtures'))
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .map((name) => ({
+      name: name.replace(/\.json$/, ''),
+      expects: 'result',
+      ...JSON.parse(fs.readFileSync(path.join(SHARED, 'fixtures', name), 'utf8')),
+    }))
+  : [];
+
+const answered = cases.filter((testCase) => testCase.expects === 'result');
+const malformed = cases.filter((testCase) => testCase.expects === 'input_error');
+
+const OPERATIONS = {
+  quote: commerce.quote,
+  evaluate_policy: commerce.evaluatePolicy,
+  catalog_version_info: commerce.catalogVersionInfo,
+};
+
+function run(testCase) {
+  return OPERATIONS[testCase.operation](testCase.document, testCase.request);
+}
+
+const MINIMAL_DOCUMENT = {
+  tariffs: [{
+    carrier_id: 'acme',
+    service_id: 'ground',
+    versions: [{
+      effective_at: 0,
+      dimensional_weight_divisor: 5000,
+      cost_per_dimensional_kg_minor: { 'zone-a': 450 },
+      minimum_charge_minor: 900,
+      fuel_surcharge_permille: 120,
+      accessorials: [{ accessorial_id: 'liftgate', flat_charge_minor: 250 }],
+    }],
+  }],
+};
+
+function shipment(overrides = {}) {
+  const request = {
+    carrier_id: 'acme',
+    service_id: 'ground',
+    tariff_version: 1,
+    zone: 'zone-a',
+    actual_weight_g: 1200,
+    volume_mm3: 6000000,
+    ...overrides,
+  };
+  return Object.fromEntries(Object.entries(request).filter(([, value]) => value !== null));
+}
+
+if (!hasFixtures) {
+  test('the shared commerce fixtures are not part of this package', { skip: true }, () => {});
+}
+
+for (const testCase of answered) {
+  test(`${testCase.name} matches the golden document`, () => {
+    const golden = fs.readFileSync(path.join(SHARED, 'golden', `${testCase.name}.json`), 'utf8');
+
+    assert.equal(canonicalJson(run(testCase)), golden.trim(), testCase.description);
+  });
+}
+
+for (const testCase of malformed) {
+  test(`${testCase.name} is refused rather than answered`, () => {
+    assert.throws(() => run(testCase), CommerceInputError, testCase.description);
+  });
+}
+
+if (hasFixtures) {
+  test('the fixture set still covers every documented rejection code', () => {
+    const produced = answered
+      .map(run)
+      .filter((result) => result.status === 'rejected')
+      .map((result) => result.error.code);
+
+    assert.deepEqual([...new Set(produced)].sort(), [...commerce.REJECTION_CODES].sort());
+  });
+
+  test('the native backend agrees with the fallback wherever both can answer', (t) => {
+    const require = createRequire(import.meta.url);
+    let native = null;
+    // The same specifiers `force-fallback.cjs` blocks, so a coverage run pinned to the
+    // fallback cannot accidentally load -- and measure -- the native addon here.
+    for (const candidate of ['./packvium-native.node', '@packvium/native',
+      '../../packvium-rust/bindings/node']) {
+      try { native = require(candidate); break; } catch { /* not installed or blocked */ }
+    }
+    if (!native?.commerceQuoteJson) {
+      t.skip('no native addon exporting the commerce surface is loadable here');
+      return;
+    }
+    const entries = {
+      quote: native.commerceQuoteJson,
+      evaluate_policy: native.commerceEvaluatePolicyJson,
+      catalog_version_info: native.commerceCatalogVersionInfoJson,
+    };
+    for (const testCase of answered) {
+      const call = JSON.stringify({ document: testCase.document, request: testCase.request });
+      // Compared as canonical text rather than as objects, so neither key order nor a
+      // deep-equality coercion can hide a difference between the two backends.
+      assert.equal(
+        canonicalJson(JSON.parse(entries[testCase.operation](call))),
+        canonicalJson(run(testCase)),
+        `${testCase.name}: the native and fallback backends disagree`,
+      );
+    }
+  });
+}
+
+test('a malformed request is a caller error, not a rejection', () => {
+  for (const overrides of [
+    { zone: 7 },
+    { actual_weight_g: -1 },
+    { actual_weight_g: true },
+    { requested_accessorials: ['liftgate', 'liftgate'] },
+    { discount_code: 'FREE' },
+    { tariff_version: null },
+    { as_of: 0 },
+  ]) {
+    assert.throws(() => quote(MINIMAL_DOCUMENT, shipment(overrides)), CommerceInputError,
+      `expected ${JSON.stringify(overrides)} to be refused`);
+  }
+});
+
+test('an unpriceable zone is an answer, not an exception', () => {
+  const result = quote(MINIMAL_DOCUMENT, shipment({ zone: 'zone-nowhere' }));
+
+  assert.equal(result.status, 'rejected');
+  assert.deepEqual(result.error, {
+    code: 'unavailable_zone',
+    fields: {
+      carrier_id: 'acme', service_id: 'ground', tariff_version: 1, zone: 'zone-nowhere',
+    },
+  });
+});
+
+test('a permille accessorial and a minimum charge both round up', () => {
+  const document = {
+    tariffs: [{
+      carrier_id: 'acme',
+      service_id: 'ground',
+      versions: [{
+        effective_at: 0,
+        dimensional_weight_divisor: 5000,
+        cost_per_dimensional_kg_minor: { 'zone-a': 1 },
+        minimum_charge_minor: 7,
+        fuel_surcharge_permille: 1,
+        accessorials: [{ accessorial_id: 'residential', permille_of_base: 1 }],
+      }],
+    }],
+  };
+
+  const result = quote(document, shipment({
+    actual_weight_g: 1, volume_mm3: 1, requested_accessorials: ['residential'],
+  }));
+
+  assert.equal(result.quote.minimum_charge_applied, true);
+  assert.equal(result.quote.base_charge_minor, 7);
+  assert.equal(result.quote.fuel_surcharge_minor, 1, 'ceil(7 * 1 / 1000) is 1, never 0');
+  assert.deepEqual(result.quote.accessorial_charges_minor, [['residential', 1]]);
+  assert.equal(result.quote.total_minor, 9);
+});
+
+test('canonical output is independent of input key order', () => {
+  const forward = shipment();
+  const reversed = Object.fromEntries(Object.entries(forward).reverse());
+
+  assert.equal(
+    canonicalJson(quote(MINIMAL_DOCUMENT, forward)),
+    canonicalJson(quote(MINIMAL_DOCUMENT, reversed)),
+  );
+});
diff --git a/test/fallback.test.mjs b/test/fallback.test.mjs
index bb58ee2..4065c80 100644
--- a/test/fallback.test.mjs
+++ b/test/fallback.test.mjs
@@ -1142,11 +1142,124 @@ test('a bracket step makes two different billed weights cost exactly the same',
   assert.notDeepEqual(billable[0], billable[1]);
 });
 
-test('a weight the tariff does not price ranks worst, never free', () => {
+test('a weight the tariff does not price is never reported as an answer', () => {
   // Billed 1000 g against a ladder that stops at 500 g. Scoring an unpriceable container
-  // as 0 would make this objective actively prefer the packing the caller cannot ship.
-  const result = packFallback(landed({ weight_brackets_g: [500], prices_minor: [700] }, '200 g'));
-  assert.equal(result.score[1], Number.MAX_SAFE_INTEGER);
+  // as 0 would make this objective actively prefer the packing the caller cannot ship,
+  // so it still ranks worst *during* search -- that is what lets a priceable container
+  // win a round. This asks the other half: with no priceable alternative on offer, the
+  // sentinel must not surface. It used to -- the run returned `feasible` with a
+  // landed cost of MAX_SAFE_INTEGER, quoting a price the carrier never published.
+  assert.throws(
+    () => packFallback(landed({ weight_brackets_g: [500], prices_minor: [700] }, '200 g')),
+    /container "c" bills at 1000 g, above its rate table's last bracket \(500 g\); the shipment has no published price/,
+  );
+});
+
+test('an unpriceable container loses to a priceable one in the general greedy path', () => {
+  // Eight units is past the single-item shape the compact path takes, and `try_grid`
+  // stands down for this objective anyway, so this lands in the general per-round key.
+  // That key was `[-placed, cost_minor, unused]` -- it never looked at the objective at
+  // all -- so it chose the snuggest box, and the snuggest box here is the one whose
+  // tariff runs out at 2000 g while it bills at 5400 g. The looser container prices the
+  // same load at 1500. The money-first round key prices each trial instead;
+  // Rust reaches the identical answer through `container_selection_key`.
+  const req = request(
+    [cube('box', 100, { weight: '500 g', quantity: 8 })],
+    [
+      box('alpha_unpriceable', 300, 300, 300, { rate_table: { weight_brackets_g: [2000], prices_minor: [900] } }),
+      box('beta_priceable', 400, 400, 400, { rate_table: { weight_brackets_g: [20000], prices_minor: [1500] } }),
+    ],
+    {
+      configuration: {
+        objective: 'lowest_landed_cost',
+        dimensional_weight_divisor: 5000,
+        dimensional_weight_length_unit: 'cm',
+        dimensional_weight_weight_unit: 'kg',
+      },
+    },
+  );
+  const result = packFallback(req);
+  assert.equal(result.containers.length, 1);
+  assert.equal(result.containers[0].container_type, 'beta_priceable');
+  assert.equal(result.score[1], 1500);
+  assert.equal(result.unpacked_items.length, 0);
+});
+
+test('a bracket step makes the cheaper shipment the heavier one', () => {
+  // Ranking by billed weight and ranking by money agree only while price rises smoothly
+  // with weight. `heavy_but_cheap` bills at 12800 g for 400; `light_but_dear` bills at
+  // 5400 g -- less than half -- for 900. The objective is named lowest_landed_*cost*.
+  const req = request(
+    [cube('box', 100, { weight: '500 g', quantity: 8 })],
+    [
+      box('light_but_dear', 300, 300, 300, { rate_table: { weight_brackets_g: [20000], prices_minor: [900] } }),
+      box('heavy_but_cheap', 400, 400, 400, { rate_table: { weight_brackets_g: [20000], prices_minor: [400] } }),
+    ],
+    {
+      configuration: {
+        objective: 'lowest_landed_cost',
+        dimensional_weight_divisor: 5000,
+        dimensional_weight_length_unit: 'cm',
+        dimensional_weight_weight_unit: 'kg',
+      },
+    },
+  );
+  const result = packFallback(req);
+  assert.equal(result.containers[0].container_type, 'heavy_but_cheap');
+  assert.equal(result.score[1], 400);
+});
+
+test('an unpriceable trial cannot win the round on placing more items', () => {
+  // The snug box holds both bricks but bills 2000 g against a ladder that stops at
+  // 1500 g; the per-unit box ships one brick at 100. A round key that ranked progress
+  // first committed the snug box and refused this request, while Rust, Python and PHP
+  // ship it in two per-unit boxes at 200 ( second review).
+  const req = request(
+    [cube('brick', 100, { weight: '1000 g', quantity: 2 })],
+    [
+      box('snug_unpriceable', 200, 100, 100, { rate_table: { weight_brackets_g: [1500], prices_minor: [900] } }),
+      box('unit_priced', 100, 100, 100, { rate_table: { weight_brackets_g: [1500], prices_minor: [100] } }),
+    ],
+    {
+      configuration: {
+        objective: 'lowest_landed_cost',
+        dimensional_weight_divisor: 5000,
+        dimensional_weight_length_unit: 'cm',
+        dimensional_weight_weight_unit: 'kg',
+      },
+    },
+  );
+  const result = packFallback(req);
+  assert.deepEqual(result.containers.map((c) => c.container_type), ['unit_priced', 'unit_priced']);
+  assert.equal(result.score[1], 200);
+  assert.equal(result.unpacked_items.length, 0);
+});
+
+test('the round key ranks money ahead of progress, matching the other engines', () => {
+  // Both containers are priceable: the snug box takes both bricks in one round for
+  // 5000, the per-unit box takes one brick for 100. Ranking progress first paid the
+  // 5000 -- 25x the answer Rust, Python and PHP return -- and the engines split
+  // silently, because the corpus fixtures tie the placed counts. Money first, two
+  // per-unit rounds at 200 win; the finished score agrees this is the better packing.
+  const req = request(
+    [cube('brick', 100, { weight: '1000 g', quantity: 2 })],
+    [
+      box('snug_dear', 200, 100, 100, { rate_table: { weight_brackets_g: [20000], prices_minor: [5000] } }),
+      box('unit_cheap', 100, 100, 100, { rate_table: { weight_brackets_g: [1500], prices_minor: [100] } }),
+    ],
+    {
+      configuration: {
+        objective: 'lowest_landed_cost',
+        dimensional_weight_divisor: 5000,
+        dimensional_weight_length_unit: 'cm',
+        dimensional_weight_weight_unit: 'kg',
+      },
+    },
+  );
+  const result = packFallback(req);
+  assert.deepEqual(result.containers.map((c) => c.container_type), ['unit_cheap', 'unit_cheap']);
+  assert.equal(result.score[1], 200);
+  assert.equal(result.unpacked_items.length, 0);
 });
 
 test('the compact lattice path no longer commits to an unpriceable container (quality profile)', () => {
@@ -1158,10 +1271,10 @@ test('the compact lattice path no longer commits to an unpriceable container (qu
   // `balanced` general search, prices every candidate container exactly rather than by
   // proxy, so it is the one shape that already gets this right; this pins that it stays
   // right now that the compact path is excluded rather than silently overriding it.
-  //  tracks the residual gap: the default `balanced` profile's own general search
-  // uses the same proxy as the excluded compact path and can still choose wrong on a
-  // larger request, which needs the quality search's exact per-candidate pricing wired
-  // into the default path rather than a fast-path exclusion to close.
+  // The residual gap  tracked -- the default `balanced` profile's general search
+  // sharing the excluded fast path's proxy -- is closed by the per-round key pricing
+  // each trial; `an unpriceable container loses to a priceable one in the general
+  // greedy path` above is the case that used to fail.
   const req = request(
     [cube('dense', 100, { weight: '500 g' })],
     [
@@ -1201,6 +1314,226 @@ test('lowest_landed_cost refuses a request it cannot price', () => {
   )), /requires configuration\.dimensional_weight_divisor/);
 });
 
+// One pinned solver crams everything into the snug box, the other splits the load and
+// prices it. `extreme_points` (volume-descending) seats the lid first and stacks every
+// brick on it, so both boxes take all nine items in one round; both bill 3300 g, the
+// tie falls to the snug box, and its ladder stops at 2000 g -- unpriceable. `layer`
+// (height-descending) floors the bricks first, which walls the lid out of the spot the
+// other order used, so it ships bricks in the snug box (1350 g billed, 900) and the lid
+// in the roomy one (2500 g billed, 1500).
+const splitPortfolio = (betaBracketG, extra = {}) => request(
+  [
+    { id: 'lid', dimensions: mm(300, 300, 100), weight: '2500 g' },
+    { id: 'brick', dimensions: mm(100, 100, 150), weight: '100 g', quantity: 8 },
+  ],
+  [
+    box('alpha_snug', 300, 300, 300, { rate_table: { weight_brackets_g: [2000], prices_minor: [900] } }),
+    box('beta_room', 400, 400, 250, { rate_table: { weight_brackets_g: [betaBracketG], prices_minor: [1500] } }),
+  ],
+  {
+    configuration: {
+      objective: 'lowest_landed_cost',
+      dimensional_weight_divisor: 20000,
+      dimensional_weight_length_unit: 'cm',
+      dimensional_weight_weight_unit: 'kg',
+      minimum_support_ratio: 1,
+      solvers: ['extreme_points', 'layer'],
+      alternatives: 3,
+      ...extra,
+    },
+  },
+);
+
+test('a portfolio returns the priceable sibling instead of propagating a child run refusal', () => {
+  // The engine used to throw the no-published-price refusal inside the extreme_points
+  // child run, aborting the request its layer sibling could price at 2400. The refusal
+  // now fires once, at the outermost frame, on the packing actually selected for
+  // return -- the choke point Rust, Python and PHP already refuse at ( second
+  // review) -- so the priceable sibling wins on the ordinary score comparison.
+  const result = packFallback(splitPortfolio(2600));
+  assert.equal(result.status, 'feasible');
+  assert.equal(result.score[1], 2400);
+  assert.deepEqual(result.containers.map((container) => container.container_type), ['alpha_snug', 'beta_room']);
+  assert.equal(result.unpacked_items.length, 0);
+  assert.ok(!('unpriceableDetail' in result));
+});
+
+test('alternatives never surface the unpriceable sentinel', () => {
+  // The losing extreme_points run carries score[1] = MAX_SAFE_INTEGER. The sentinel is
+  // a search device, never an answer -- alternatives included ( review): the run
+  // is filtered out rather than offered as a packing costing 2^53-1 minor units.
+  const filtered = packFallback(splitPortfolio(2600));
+  assert.equal(filtered.alternatives.length, 0);
+  assert.ok(!JSON.stringify(filtered).includes('9007199254740991'));
+  // With the roomy box's ladder raised both runs price, the winner flips to the
+  // single-container packing, and the sibling is reported: the filter removes
+  // sentinels, not siblings.
+  const populated = packFallback(splitPortfolio(20000));
+  assert.equal(populated.score[1], 1500);
+  assert.equal(populated.alternatives.length, 1);
+  assert.equal(populated.alternatives[0].score[1], 2400);
+  assert.ok(populated.alternatives.every((alternative) => !('unpriceableDetail' in alternative)));
+  assert.ok(!JSON.stringify(populated).includes('9007199254740991'));
+});
+
+test('a child run hands its unpriceable packing to the portfolio instead of throwing', () => {
+  // Billed 1000 g against a ladder that stops at 500 g, with no sibling to win. The
+  // refusal is the outermost frame's job: a solver child and a seeded-start child must
+  // both return the sentinel-scored result, because throwing there is what aborted
+  // portfolios whose other runs had a priceable answer. The detail steering the
+  // outermost frame is non-enumerable and never serializes.
+  for (const [solverAlias, startIndex] of [['extreme_points', null], [null, 1]]) {
+    const run = packFallback(
+      landed({ weight_brackets_g: [500], prices_minor: [700] }, '200 g'),
+      Date.now, solverAlias, startIndex,
+    );
+    assert.equal(run.score[1], Number.MAX_SAFE_INTEGER);
+    assert.deepEqual(run.unpriceableDetail, { id: 'c', grams: 1000, bound: 500 });
+    assert.equal(Object.getOwnPropertyDescriptor(run, 'unpriceableDetail').enumerable, false);
+    assert.ok(!JSON.stringify(run).includes('unpriceableDetail'));
+  }
+});
+
+test('a portfolio with no priceable run anywhere still refuses at the outermost frame', () => {
+  // Every pinned solver, every seeded start and every quality re-entry reaches the same
+  // unpriceable packing; deferring the refusal to the outermost frame must not soften
+  // it into a sentinel-scored answer.
+  const refusal = /container "c" bills at 1000 g, above its rate table's last bracket \(500 g\); the shipment has no published price/;
+  for (const configuration of [
+    { solvers: ['extreme_points', 'layer'] },
+    { multi_start_orders: 2 },
+    { solver_profile: 'quality' },
+  ]) {
+    const req = landed({ weight_brackets_g: [500], prices_minor: [700] }, '200 g');
+    req.configuration = { ...req.configuration, ...configuration };
+    assert.throws(() => packFallback(req), refusal);
+  }
+});
+
+test('the quality portfolio prices the  scene instead of refusing it', () => {
+  // The second-review scene: eight 500 g cubes, a snug box whose ladder stops at 2000 g
+  // and a roomy one priced to 20000 g. Each quality-profile child settles on the roomy
+  // box, and the portfolio must ship it at 1500 rather than refuse because some frame
+  // ranked the snug box along the way.
+  const req = request(
+    [cube('box', 100, { weight: '500 g', quantity: 8 })],
+    [
+      box('alpha_unpriceable', 300, 300, 300, { rate_table: { weight_brackets_g: [2000], prices_minor: [900] } }),
+      box('beta_priceable', 400, 400, 400, { rate_table: { weight_brackets_g: [20000], prices_minor: [1500] } }),
+    ],
+    {
+      configuration: {
+        objective: 'lowest_landed_cost',
+        solver_profile: 'quality',
+        dimensional_weight_divisor: 5000,
+        dimensional_weight_length_unit: 'cm',
+        dimensional_weight_weight_unit: 'kg',
+      },
+    },
+  );
+  const result = packFallback(req);
+  assert.equal(result.status, 'feasible');
+  assert.equal(result.containers[0].container_type, 'beta_priceable');
+  assert.equal(result.score[1], 1500);
+});
+
+test('rebalancing refuses an input packing the tariff cannot price', () => {
+  // Same admission the solve path applies, in the same words: a packing that already
+  // bills past its rate table's last bracket has no published price to rebalance around.
+  const req = request(
+    [cube('a', 100, { weight: '1000 g' })],
+    [box('c', 200, 200, 200, { rate_table: { weight_brackets_g: [500], prices_minor: [700] } })],
+  );
+  const original = packSound(req);
+  const landedReq = {
+    ...req,
+    configuration: {
+      objective: 'lowest_landed_cost',
+      dimensional_weight_divisor: 8000,
+      dimensional_weight_length_unit: 'cm',
+      dimensional_weight_weight_unit: 'kg',
+    },
+  };
+  assert.throws(
+    () => rebalanceWeight(landedReq, original),
+    /container "c" bills at 1000 g, above its rate table's last bracket \(500 g\); the shipment has no published price/,
+  );
+});
+
+test('rebalancing applies the same landed-cost admission as packing', () => {
+  // The current packing uses only `rated`, but `untabled` remains a request option.
+  // Letting the direct rebalance API ignore it would make its contract weaker than
+  // packFallback and the native implementation ( second review).
+  const base = request(
+    [cube('parcel', 100, { weight: '500 g' })],
+    [box('rated', 200, 200, 200, { rate_table: { weight_brackets_g: [2000], prices_minor: [500] } })],
+  );
+  const original = packSound(base);
+  assert.throws(
+    () => rebalanceWeight({ ...base, configuration: { objective: 'lowest_landed_cost' } }, original),
+    /requires configuration\.dimensional_weight_divisor/,
+  );
+  const withUntabled = {
+    ...base,
+    containers: [...base.containers, box('untabled', 300, 300, 300)],
+    configuration: {
+      objective: 'lowest_landed_cost',
+      dimensional_weight_divisor: 8000,
+      dimensional_weight_length_unit: 'cm',
+      dimensional_weight_weight_unit: 'kg',
+    },
+  };
+  assert.throws(
+    () => rebalanceWeight(withUntabled, original),
+    /requires a rate_table on every container; "untabled" has none/,
+  );
+});
+
+test('a rebalance move that would leave the destination unpriceable is vetoed', () => {
+  // Three 500 g bricks in the big box against a 100 g pebble in the tight one. Moving a
+  // brick narrows the spread from 1400 g to 400 g, but bills the tight box at 600 g
+  // against a ladder that stops at 500 g: under `lowest_landed_cost` that trade sells
+  // balance for a shipment with no published price, so every such candidate fails
+  // exactly like an invalid one. The same scene under the default objective keeps
+  // moving, so anything not landed-priced is untouched by the guard.
+  const req = request(
+    [
+      cube('brick', 100, { weight: '500 g', quantity: 3 }),
+      cube('pebble', 100, { weight: '100 g' }),
+    ],
+    [
+      box('alpha_hold', 300, 300, 300, { max_items: 3, rate_table: { weight_brackets_g: [20000], prices_minor: [900] } }),
+      box('gamma_tight', 200, 200, 200, { max_items: 2, rate_table: { weight_brackets_g: [500], prices_minor: [300] } }),
+    ],
+  );
+  const original = packSound(req);
+  assert.deepEqual(
+    original.containers.map((container) => container.payload_weight.ticks),
+    [1500 * 8_000_000, 100 * 8_000_000],
+  );
+  const landedReq = {
+    ...req,
+    configuration: {
+      objective: 'lowest_landed_cost',
+      dimensional_weight_divisor: 20000,
+      dimensional_weight_length_unit: 'cm',
+      dimensional_weight_weight_unit: 'kg',
+    },
+  };
+  const vetoed = rebalanceWeight(landedReq, original, { maxMoves: 8 });
+  assert.deepEqual(vetoed.moves, []);
+  assert.equal(vetoed.improved, false);
+  assert.deepEqual(vetoed.containers, original.containers);
+  const balanced = rebalanceWeight(req, original, { maxMoves: 8 });
+  assert.deepEqual(balanced.moves, [
+    { item_id: 'brick#1', from_container_id: 'alpha_hold#1', to_container_id: 'gamma_tight#2' },
+  ]);
+  assert.deepEqual(
+    balanced.containers.map((container) => container.payload_weight.ticks),
+    [1000 * 8_000_000, 600 * 8_000_000],
+  );
+});
+
 // ---------------------------------------------------- staged rollout
 
 test('the guard refuses exactly the fields the unsupported lists name', () => {
@@ -1427,6 +1760,28 @@ test('exact_small searches equal-count branches for a better objective tie-break
   );
 });
 
+test('exact_small does not prune a heavier promotional rate band', () => {
+  const payload = request(
+    [
+      cube('a-light', 100, { weight: '100 g' }),
+      cube('b-light', 100, { weight: '100 g' }),
+      cube('z-heavy', 100, { weight: '800 g' }),
+    ],
+    [box('bin', 200, 100, 100, {
+      quantity: 1,
+      rate_table: { weight_brackets_g: [200, 900], prices_minor: [100, 10] },
+    })],
+    { configuration: {
+      solvers: ['exact_small'], objective: 'lowest_landed_cost', max_containers: 1,
+      dimensional_weight_divisor: 10000,
+      dimensional_weight_length_unit: 'cm', dimensional_weight_weight_unit: 'kg',
+    } },
+  );
+  const result = packFallback(payload);
+  assert.deepEqual(result.score.slice(0, 2), [1, 10]);
+  assert.ok(placements(result).some(placement => placement.item_id === 'z-heavy#1'));
+});
+
 test('exact_small stops at an admissible complete objective floor', () => {
   const payload = request(
     [cube('cube', 45, { quantity: 8, allowed_rotations: ['LWH'] })],
diff --git a/test/force-fallback.cjs b/test/force-fallback.cjs
index a1df4a2..fd444e1 100644
--- a/test/force-fallback.cjs
+++ b/test/force-fallback.cjs
@@ -14,8 +14,20 @@
 
 const Module = require('node:module');
 
+// Exactly what `index.js` probes, and nothing else -- `force-fallback.test.mjs` asserts
+// the two lists stay identical, which is what makes "this hook blocks the package's
+// native backend" a checkable claim rather than a comment.
 const NATIVE_CANDIDATES = ['./packvium-native.node', '@packvium/native'];
 
+// Paths only a test reaches for: the in-workspace build directory the commerce suite
+// loads when it compares the native and fallback backends against each other. Blocked
+// too, because "forced fallback" has to mean forced everywhere -- a suite that loaded
+// the addon by a path this hook did not know would measure the wrong backend and pull a
+// file outside `package.json`'s `files` into the coverage report.
+const TEST_ONLY_CANDIDATES = ['../../packvium-rust/bindings/node'];
+
+const BLOCKED = [...NATIVE_CANDIDATES, ...TEST_ONLY_CANDIDATES];
+
 class NativeBackendBlockedError extends Error {
   constructor(specifier) {
     super(`native backend '${specifier}' is blocked: this process is pinned to the JavaScript fallback`);
@@ -26,8 +38,8 @@ class NativeBackendBlockedError extends Error {
 
 const nextResolveFilename = Module._resolveFilename;
 Module._resolveFilename = function resolveWithoutNativeBackend(request, parent, isMain, options) {
-  if (NATIVE_CANDIDATES.includes(request)) throw new NativeBackendBlockedError(request);
+  if (BLOCKED.includes(request)) throw new NativeBackendBlockedError(request);
   return nextResolveFilename.call(this, request, parent, isMain, options);
 };
 
-module.exports = { NATIVE_CANDIDATES, NativeBackendBlockedError };
+module.exports = { NATIVE_CANDIDATES, TEST_ONLY_CANDIDATES, NativeBackendBlockedError };