@packvium/engine 0.1.0 → 0.1.2

package/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,14 +114,33 @@ 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.
 
+## The Packvium family
+
+One request and result contract, implemented independently in four engines (Rust,
+Python, PHP, JavaScript) and held to identical placements on a shared fixture set.
+Pick the package for your stack; mixing them in one system is safe.
+
+| Package | Install | Source |
+| --- | --- | --- |
+| Python — [`packvium`](https://pypi.org/project/packvium/) | `pip install packvium` | [packvium-python](https://github.com/toxakara/packvium-python) |
+| PHP — [`packvium/packvium`](https://packagist.org/packages/packvium/packvium) | `composer require packvium/packvium` | [packvium-php](https://github.com/toxakara/packvium-php) |
+| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "0.1"` | [packvium-rust](https://github.com/toxakara/packvium-rust) |
+| Node.js — [`@packvium/engine`](https://www.npmjs.com/package/@packvium/engine) | `npm install @packvium/engine` | [packvium-node](https://github.com/toxakara/packvium-node) |
+| Browser / WebAssembly — [`@packvium/browser`](https://www.npmjs.com/package/@packvium/browser) | `npm install @packvium/browser` | [packvium-wasm](https://github.com/toxakara/packvium-wasm) |
+| PHP FFI bridge — [`packvium/native-bridge`](https://packagist.org/packages/packvium/native-bridge) | `composer require packvium/native-bridge` | [packvium-php-bridge](https://github.com/toxakara/packvium-php-bridge) |
+| Python native selector — `packvium-native` | from source until the native wheels ship | [packvium-python-adapter](https://github.com/toxakara/packvium-python-adapter) |
+
 ## 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
 

package/SECURITY.md

@@ -0,0 +1,77 @@
+# Security policy
+
+## Supported versions
+
+Only the latest `0.1.x` release receives fixes. This is an early release; there is no
+long-term support branch yet.
+
+## Reporting a vulnerability
+
+Please report privately, not in a public issue. Use GitHub's **Report a vulnerability**
+button under the Security tab, which opens a private advisory.
+
+Include the version, the platform, a minimal request that reproduces the problem, and
+what you observed. A crash, a hang or a wildly wrong result on a small input is worth
+reporting even if you are unsure it is a security matter.
+
+You can expect an acknowledgement within a few working days and an assessment after that.
+Please give us a chance to ship a fix before disclosing publicly.
+
+## Threat model
+
+This is a computation library. It has **no runtime dependencies**, opens no network
+connections, spawns no processes, reads no files except through the CLI's standard input,
+and executes no user-supplied code except the extension objects you register yourself.
+
+The realistic risks are therefore about untrusted **input**:
+
+- **Resource exhaustion.** A request with a large item count, many container types or a
+  permissive solver profile can consume substantial CPU and memory. If you accept
+  requests from untrusted callers, set `time_limit_ms`, cap item quantities and container
+  inventory, and run the call where you can bound memory. The deadline is honoured by the
+  search, but a single enormous request can still allocate a lot before the first check.
+- **Integer magnitude.** Dimensions are converted to exact integer ticks — 16 000 per
+  millimetre. Absurd inputs produce very large integers rather than overflow, but they
+  cost time and memory. Validate dimensions against a sane maximum before passing them in.
+- **Malformed input.** Bad units, unparseable numbers and contradictory constraints raise
+  errors rather than producing a wrong packing. Do not suppress those errors.
+
+A result that reports success has passed independent validation, but validation checks
+the constraints you declared. It cannot know about a constraint you did not express.
+
+## Extensions
+
+Custom constraints, orderings, scorers, container selectors and solvers run with the
+privileges of your process. Treat a third-party extension as you would any other
+dependency: read it before you register it.
+
+## Signing and keyless publishing
+
+Every release is built and published from CI, never from a maintainer's workstation,
+so there is one attacker-controlled surface to defend: the release workflow itself.
+
+- **Signed tags.** The tag a release is cut from is a signed git tag (`git tag -s`),
+  verifiable against the maintainers' published keys. An unsigned tag is not released
+  from.
+- **OIDC trusted publishing instead of long-lived tokens, where the registry supports
+  it.** PyPI and npm both accept a short-lived token minted from the release workflow's
+  GitHub Actions OIDC identity instead of a static API token stored as a secret — there
+  is no password to leak because none is issued until the moment of publish, and it is
+  scoped to that one run. Packagist resolves packages directly from the tagged git
+  repository and has no comparable upload token to eliminate. crates.io does not yet
+  support trusted publishing for this ecosystem; until it does, its token is scoped to
+  this crate only, stored as a CI secret, and rotated on the schedule below regardless
+  of whether compromise is suspected.
+- **Provenance attestations** (see the release process)
+  bind each published artifact back to the exact workflow run, commit and tag that
+  produced it, independent of which upload method the registry used.
+- **Recovery.** If the release workflow, its OIDC trust configuration or the crates.io
+  token is suspected compromised: revoke the trust relationship (or rotate the token)
+  immediately, audit the workflow's recent runs and any artifacts they published,
+  and re-cut the release from a clean, re-reviewed commit under a new version — never
+  by force-pushing or reusing the affected tag.
+- **Revocation.** A compromised or defective published version is pulled from
+  circulation using each registry's own mechanism (PyPI yank, npm deprecate, Packagist
+  abandon, crates.io yank) rather than deleted outright, so that projects already
+  pinned to it get a clear signal instead of a broken install. The security advisory
+  for the issue names the affected versions explicitly.

package/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,
+    },
+  };
+}