Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,65 @@ What changed in `packvium` on crates.io, release by release. The format follows
[Keep a Changelog](https://keepachangelog.com/1.1.0/) and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.7.0]

The reference validator ships in the crate, `quality` looks ahead in its block solver and
finishes inside its time limit, and extreme points scan the candidate set they were meant to.
No request or result field changes.

### Added

- **`validate_json(request, result)` and `validate_json_outcome`**, with `ResultIssue`,
`MalformedResult { kind, message }` and `RefusalKind`: the reference validator over the JSON
text, returning the same issues, code and detail, in the same order, as every other package.
It shares no code with the solvers or `IndependentValidator`, which is unchanged.
- **`PlacementConstraint::distinguishes_instances`**, a defaulted trait method, `true` unless
overridden, so existing implementations compile and keep their behaviour. A constraint that
reads only item attributes may return `false` to let the portfolio drop a start order that
repeats another's item-type sequence.

### Changed

- **A `CandidateScorer` leads the extreme-point rank.** The rank is the tuple (sum of
scorer scores, far corner z, y, x, origin, rotation); before, a scorer's `score` was added to
one weighted sum of the far-corner ticks at the weight of one x tick. A scorer that returned
small nudges meant as tie-breaks now decides the rank; return 0 where it has no preference.
The trait's signature is unchanged, and no request without a custom scorer answers
differently on the measured corpora.
- **Every schema enum value is refused as `not_allowed`.** A value outside its list in
`allowed_rotations`, the output and dimensional-weight units, `shape_type`,
`ground_contact_rule` or `configuration.solvers` is `invalid_request` with reason `not_allowed`
at its JSON Pointer. An unknown output unit was copied through; **`ticks` as an output unit is
now refused**, as the schema always said.
- **`quality` looks ahead in the block solver**, completing its leading blocks greedily
and committing the best, so the answer is never worse than the greedy pass. On our benchmark
85 of 89 answers improved and none got worse. Under a tight effort budget the block start can
now report `truncated` / `effort_limit`.
- **`quality` finishes inside its limit.** The staged beam refines the best greedy
order instead of the first two, and the spatial index stops at the first hit without
allocating. On the 22 pinned benchmark runs 1.6.0 needed more than 20 s of CPU on 10; this
release needs at most 8.1 s.
- **Extreme points scan the exposed corners and their projections**, not every
combination of placed faces. With `solvers: ["extreme_points"]` alone, over 67 benchmark
instances, `fast`/`balanced`/`quality` leave 2711/1477/1297 items out instead of
3658/3048/2643. The full portfolio's answers did not change on the 89 benchmark requests, and
its `quality` CPU fell to 42%.
- **Portfolio starts go to distinct item orders.** A start that repeats another's
item-type sequence runs a neighbouring order instead, kept only on a strict win. A stacking
scene that took two containers now takes one.
- **`no_eligible_container` is reported `proven`, and `insufficient_support` is reported**
(`observed`) where the support rule is the only blocker.
- **A `nesting_height` not below the item's height is refused as `invalid_value`** at its
pointer, and with no `output` block the result is written in `units.length`'s schema code.

### Fixed

- **`incompatible_tags` is applied item against item**, not against container tags, as the
validator and every other engine apply it.
- **A panicking start fails a parallel portfolio** as it fails a sequential one; it was dropped.
- **Axle-balanced candidate points use the envelope length under clearance** and are not offered
twice.

## [1.6.0]

Boxes cut to measure, flat bags, stacking groups and a volume-first objective, and a fix for
Expand Down
2 changes: 1 addition & 1 deletion CITATION.cff
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ type: software
authors:
- name: "Packvium contributors"
website: "https://packvium.com"
version: "1.6.0"
version: "1.7.0"
license: MIT
url: "https://packvium.com"
repository-code: "https://github.com/toxakara/packvium-rust"
Expand Down
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "packvium"
version = "1.6.0"
version = "1.7.0"
edition = "2024"
rust-version = "1.88"
license = "MIT"
Expand Down
40 changes: 33 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,21 @@ coordinates and rotations for each item, with a reason for anything that did not
Full documentation, the constraint reference and benchmarks live at
[packvium.com](https://packvium.com).

> **Version 1.6.0 — the public API is frozen.** Field names, status codes and the
> **Version 1.7.0 — the public API is frozen.** Field names, status codes and the
> objective vector do not change without a major version, so any `1.x` is a safe upgrade
> from any earlier `1.x`.
> Read [docs/GUARANTEES.md](https://github.com/toxakara/packvium-rust/blob/main/docs/GUARANTEES.md)
> before relying on a result.

```sh
cargo add packvium
```

or, in `Cargo.toml`:

```toml
[dependencies]
packvium = "1.5"
packvium = "1.7"
```

## Quick start
Expand Down Expand Up @@ -75,7 +81,7 @@ cargo run --example basic
| --- | --- |
| [`basic.rs`](https://github.com/toxakara/packvium-rust/blob/main/examples/basic.rs) | An order into a carton, read back into typed structs; an item that cannot fit, and why. |
| [`constraints.rs`](https://github.com/toxakara/packvium-rust/blob/main/examples/constraints.rs) | Rotations and keep-upright, stacking limits and top load, support ratio and incompatible tags — each shown with and without the rule. |
| [`objectives.rs`](https://github.com/toxakara/packvium-rust/blob/main/examples/objectives.rs) | The six objectives, and the scenes where two of them pick different containers. |
| [`objectives.rs`](https://github.com/toxakara/packvium-rust/blob/main/examples/objectives.rs) | Six of the seven objectives (all but `maximum_volume`), and the scenes where two of them pick different containers. |
| [`units.rs`](https://github.com/toxakara/packvium-rust/blob/main/examples/units.rs) | What you can type (fractions, inches, pounds), why nothing is a float, and exact fits. |
| [`errors.rs`](https://github.com/toxakara/packvium-rust/blob/main/examples/errors.rs) | Branching on a refused request with `code()`, `reason()` and `field()`, and why an item that does not fit is not an error. |
| [`trucking.rs`](https://github.com/toxakara/packvium-rust/blob/main/examples/trucking.rs) | A delivery van: stops unloaded in route order through a named door, and axle loads kept inside their ratings. |
Expand Down Expand Up @@ -128,6 +134,25 @@ A request that is valid but does not fit completely is not an error. The result
left out, and why, in `unpacked_items`, and `packvium_core::explain_reason` turns each reason
code into a sentence.

## Checking a result

*New in 1.7.0.*

`validate_json` checks a result against the request it answers, from the JSON alone: geometry,
support and load, accounting, the result's facts and its score. It is the same reference
validator every Packvium package exports, so it returns the same issues, code and detail:

```rust
let result = packvium_core::pack_json(request)?;
let issues = packvium_core::validate_json(request, &result)?; // empty: valid
for issue in &issues {
println!("{}: {}", issue.code, issue.detail); // e.g. collision: cube#1 with cube#2 in box#1
}
```

It shares no code with the solvers, so it judges any engine's result, not only this crate's. A
result without the documented shape is `Err(MalformedResult { kind, message })`.

## Determinism

The same request gives the same placements: the only randomness is seeded from the request's
Expand All @@ -150,8 +175,9 @@ of the request, so a different seed is a different, equally reproducible request
floor-only, non-stackable, stack-count and top-load limits, minimum support ratio, tag
incompatibility, clearance and rectangular obstacles; and for vehicles, route order by
`stop_index`, unloading doors by `access_directions`, and two-axle load limits.
- **Six objectives.** Fewest containers, packaging cost, carrier-billable weight, carrier
rate cards, open-dimension height and value kept — each a vector of exact integers.
- **Seven objectives.** Fewest containers, packaging cost, carrier-billable weight, carrier
rate cards, open-dimension height, value kept and volume loaded — each a vector of exact
integers.
- **A solver portfolio, not one algorithm.** Regular-grid, layer, extreme-point,
maximal-space and bounded exact search, selected by problem shape and profile.
- **Answers you can check.** Every solution is re-validated by logic independent of the
Expand Down Expand Up @@ -205,7 +231,7 @@ Documentation, the constraint reference and the benchmarks are at
| --- | --- | --- |
| Python — [`packvium`](https://pypi.org/project/packvium/) | `pip install packvium` | [packvium-python](https://github.com/toxakara/packvium-python) |
| PHP — [`packvium/packvium`](https://packagist.org/packages/packvium/packvium) | `composer require packvium/packvium` | [packvium-php](https://github.com/toxakara/packvium-php) |
| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.5"` | [packvium-rust](https://github.com/toxakara/packvium-rust) |
| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.7"` | [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) |
Expand All @@ -228,7 +254,7 @@ CodeMeta form.
@software{packvium_rust,
author = {{Packvium contributors}},
title = {Packvium for Rust},
version = {1.6.0},
version = {1.7.0},
license = {MIT},
url = {https://packvium.com}
}
Expand Down
2 changes: 1 addition & 1 deletion codemeta.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"@type": "SoftwareSourceCode",
"name": "Packvium for Rust",
"description": "Deterministic 3D bin-packing and cartonization engine for pallets, containers, trucks and shipping cartons. Exact integer geometry, reproducible results.",
"version": "1.6.0",
"version": "1.7.0",
"license": "https://spdx.org/licenses/MIT",
"author": [
{
Expand Down
25 changes: 13 additions & 12 deletions docs/COMMERCE-API.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,9 +160,11 @@ may carry only `tariffs`. Field-level rules:
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.
- Every integer is exact. Dimensions, an item's `weight_g`, `max_payload_g`,
`max_stack_height_mm` and `dimensional_weight_divisor` must be positive; `effective_at`,
`published_at`, `cost_minor`, `minimum_charge_minor`, `fuel_surcharge_permille`,
`flat_charge_minor`, `permille_of_base` and each zone rate in
`cost_per_dimensional_kg_minor` may be zero but not negative.

### Input errors versus rejections

Expand Down Expand Up @@ -322,13 +324,12 @@ original paths and re-export the relocated definitions, so every workspace test,
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.
selector objects, which are deliberately not cross-language features: an in-process
object cannot cross the JSON boundary every other engine is driven through.

## Conformance standard

Held to the standard every other capability in this project is held to, per
TESTING-AND-RELEASE.md:
Held to the standard every other capability in this project is held to:

- **Python and PHP: byte-identical.** Both are ports of one contract; canonical JSON
(sorted keys, `,`/`:` separators, no trailing whitespace) of the result document must
Expand Down Expand Up @@ -364,15 +365,15 @@ TESTING-AND-RELEASE.md:
| `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.
the relevant history. These are the bounds of the underlying models; 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.
real carrier's published rates. Live rate-card ingestion exists, but in the carrier
connectors, not here: CARRIER-RATE-INGESTION.md builds a
table from a feed, and this API is handed the result like any other document.
- `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.
Expand Down
4 changes: 2 additions & 2 deletions docs/GUARANTEES.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ silently — if you need them, they belong in your own layer above this library.

## Status of this release

Version `1.6.0` freezes the public API. Field names, status codes, the objective
Version `1.7.0` freezes the public API. Field names, status codes, the objective
vector, the numeric policy and the validation rules do not change without a major
version, so any `1.x` is a safe upgrade from any earlier `1.x`. A caret or tilde
constraint on `1.0` is enough; an exact pin is no longer required.
Expand All @@ -61,7 +61,7 @@ What the freeze does not cover: which of several equally valid packings a solver
returns. That is bounded by the objective vector, not by the placement list, and a minor
release may return a different arrangement with the same or a better score.

The algorithm complexities documented in `ALGORITHMS-AND-COMPLEXITY.md` are asymptotic
The algorithm complexities Packvium states, in these docs and in the source, are asymptotic
design bounds held by review, not per-release measurements. They are not a wall-clock
performance contract either: constants, input shape and host all move the real number.
Use them to choose a solver profile, not to predict a duration.
Loading
Loading