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
2 changes: 1 addition & 1 deletion .github/DISCUSSION_TEMPLATE/q-a.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ body:
id: package-version
attributes:
label: Package and version
placeholder: "packvium/packvium 1.8.0 (PHP)"
placeholder: "packvium/packvium 1.9.0 (PHP)"
validations:
required: true
- type: textarea
Expand Down
2 changes: 1 addition & 1 deletion .github/DISCUSSION_TEMPLATE/show-and-tell.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ body:
id: package-version
attributes:
label: Package and version
placeholder: "packvium/packvium 1.8.0 (PHP)"
placeholder: "packvium/packvium 1.9.0 (PHP)"
validations:
required: false
- type: textarea
Expand Down
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ body:
id: version
attributes:
label: Package version
description: The exact version installed, for example 1.8.0.
placeholder: "1.8.0"
description: The exact version installed, for example 1.9.0.
placeholder: "1.9.0"
validations:
required: true
- type: input
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ body:
id: version
attributes:
label: Package version
placeholder: "1.8.0"
placeholder: "1.9.0"
validations:
required: true
- type: textarea
Expand Down
8 changes: 4 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ jobs:
matrix:
php: ["8.2", "8.3", "8.4", "8.5"]
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
- uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
with:
php-version: ${{ matrix.php }}
Expand Down Expand Up @@ -56,7 +56,7 @@ jobs:
matrix:
php: ["7.3", "7.4", "8.0", "8.1"]
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
path: package
- uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
Expand Down Expand Up @@ -111,7 +111,7 @@ jobs:
# Prove the package installs from a clean checkout the way a consumer gets it.
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
with:
path: package
- uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
Expand Down Expand Up @@ -139,7 +139,7 @@ jobs:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
- uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
with:
fail-on-severity: low
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/rc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ jobs:
verify-tag:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
- uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
with:
php-version: "8.3"
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ jobs:
verify-tag:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
- uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
with:
php-version: "8.3"
Expand Down Expand Up @@ -58,7 +58,7 @@ jobs:
permissions:
contents: write # the Release is the only thing this workflow writes to the repository
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
- name: Create the GitHub Release from the tag
env:
GH_TOKEN: ${{ github.token }}
Expand Down
37 changes: 37 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,43 @@ What changed in `packvium/packvium` on Packagist, release by release. The format
[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.9.0]

No API change, but admission is stricter: some requests 1.8 accepted are now refused (see the
weight and length limits below). More requests now agree with the reference, kilometre-scale
requests included.

### Changed

- **Under a clearance a compressible item bears its load on its own footprint**, so its crush
check is stricter and `validate` measures its own compressed volume.
- **A weight is at most `2^63 - 1` ticks, and so is every item's weight times its quantity plus
the heaviest tare**: past it, `invalid_request` / `above_maximum`; a weight written as a JSON
number past `2^53 - 1` is `invalid_value` and must be a string.
- **Agrees with the other engines where 1.8 did not:** nesting under a clearance shares the
items' own overlap and a deep nesting column nests in pairs; a length past `2^53 - 1` ticks or
a box past `10^30` cubic ticks is `invalid_request` / `above_maximum`; a side that reads as zero
ticks is `invalid_value` / `must be positive`; an obstacle box outside its container is
`invalid_value` / `lies outside inner_dimensions`, each at its own pointer.
- **`validate` checks the centroid (`centre_of_gravity_unsupported`) and the whole stack's load
(`top_load_exceeded`)**, an item on several bearers shared by contact area. It no longer
holds that item's whole weight against every bearer, so it accepts some results 1.8 rejected
and names the overloaded bearer.
- **A plan beam wider than 1 compares every container type**, whatever the node limit.
- **A request whose areas pass a 64-bit integer is answered exactly**, where it
threw a `TypeError`; `support_ratio` and `volume_utilization` are the correctly rounded
quotient, which can differ in the sixth decimal.
- **`quality` runs the full staged portfolio:** its answer and its `alternatives` now agree
with the reference, at about 0.9x the time on the measured quality fixtures.
- **`fast` is back to 1.7's peak memory on most requests** (the space-subtraction helper and the
fixed-placement and landed-cost checks load only when used).

### Fixed

- **A narrow nesting item under a clearance threw `BigInt::subtract would be negative`**, and a
deep nesting column on the lattice returned `invalid_result`.
- **Greedy `quality` starts dropped `PackingConfig::accessDirections`.**

## [1.8.0]

Results now say how far they can be from the best possible answer, `optimal` means a proof,
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.8.0"
version: "1.9.0"
license: MIT
url: "https://packvium.com"
repository-code: "https://github.com/toxakara/packvium-php"
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ 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.8.0 — the public API is frozen.** Field names, status codes and the
> **Version 1.9.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-php/blob/main/docs/GUARANTEES.md)
Expand Down Expand Up @@ -367,7 +367,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.8"` | [packvium-rust](https://github.com/toxakara/packvium-rust) |
| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.9"` | [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 @@ -391,7 +391,7 @@ CodeMeta form.
@software{packvium_php,
author = {{Packvium contributors}},
title = {Packvium for PHP},
version = {1.8.0},
version = {1.9.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 PHP",
"description": "Deterministic 3D bin-packing and cartonization engine for pallets, containers, trucks and shipping cartons. Exact integer geometry, reproducible results.",
"version": "1.8.0",
"version": "1.9.0",
"license": "https://spdx.org/licenses/MIT",
"author": [
{
Expand Down
32 changes: 32 additions & 0 deletions docs/COMMERCE-API.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,10 @@ history with a hole or a duplicated version number.
All three top-level keys are optional; a document that only needs to price a shipment
may carry only `tariffs`. Field-level rules:

- A tariff history is identified by the ordered pair `(carrier_id, service_id)`.
Separators inside either string are ordinary identifier characters: for example,
`("a/b", "c")` and `("a", "b/c")` name different histories. Duplicate detection and
both pinned and effective-dated lookup use the complete pair.
- `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.
Expand All @@ -165,6 +169,9 @@ may carry only `tariffs`. Field-level rules:
`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.
Rollback versions follow the same date bounds as snapshot versions, and a catalog
request's `resolved_at` must also be non-negative, including when its catalog or
version does not exist. These are input errors rather than lookup rejections.

### Input errors versus rejections

Expand Down Expand Up @@ -244,6 +251,16 @@ Success:
`false` `allowed` always carries a citation — the model refuses to construct a
citation-free rejection.

`equals` and `not_equals` compare JSON values recursively: list order matters,
object key order does not, and different key sets remain different even when values
are `null`. Boolean/integer equality follows the reference model (`true == 1`,
`false == 0`), including inside lists and objects. `in` and `not_in` test list
elements, string substrings, or object keys; object values are not members. A
non-string context value cannot be a substring or an object key. A missing context
field matches neither binary operator, including its negated form. Rust's rule priority
comparison handles the entire signed 64-bit range without negating its minimum;
portable JavaScript inputs remain limited by exact `Number` representation.

### `catalog_version_info`

Request:
Expand Down Expand Up @@ -368,6 +385,16 @@ The `e log e` term is sorting the three id lists; every other bound is a linear
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.

The policy rows treat predicate values as bounded. For structured values, multiply
their predicate work by the comparison/membership cost: recursive equality visits
the compared values, with an additional logarithmic key lookup per object entry in
Rust's default ordered maps. PHP and JavaScript use expected constant-time object-key
lookup; JavaScript also allocates key arrays during object comparison. Python's
effective-dated model evaluation streams version resolution and winner selection in
constant auxiliary space, excluding value-comparison recursion and the loaded
document. Each matching rule's predicates run once; the other ports retain their
existing rule-pool storage.

## Limitations

- The document is supplied by the caller. Nothing here fetches, scrapes or embeds any
Expand All @@ -380,6 +407,11 @@ parsing and serialization, both linear in the payload, and nothing else.
- 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.
- PHP's array boundary cannot recover the object/list distinction erased by an
associative JSON decoder: `{}` and `[]`, or an object with consecutive numeric
keys, can become the same PHP array. Portable object-valued predicates should use
nonempty objects with nonnumeric string keys. This limitation does not affect
list ordering or ordinary string-key object comparisons.
- 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
Expand Down
2 changes: 1 addition & 1 deletion docs/GUARANTEES.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ silently — if you need them, they belong in your own layer above this library.

## Status of this release

Version `1.8.0` freezes the public API. Field names, status codes, the objective
Version `1.9.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 Down
9 changes: 6 additions & 3 deletions docs/PUBLIC-API.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,9 @@ All counters are non-negative integers. A zero means the selected solver did not
that phase; it does not mean the metric is unsupported. Compatibility fields
`algorithm.placements_attempted` and `algorithm.candidates_evaluated` remain and must
equal `metrics.orientations_considered` and `metrics.feasible_candidates`.
For a multi-start portfolio these counters belong to the selected start; the complete
list of starts is recorded separately in `termination.starts`. Counters are not summed
across starts.
Metrics are diagnostics: they never participate in feasibility, ranking or the
objective vector.

Expand Down Expand Up @@ -469,9 +472,9 @@ bounds its work by counting must get the same answer on any machine, and a start
own share of the clock would lose quietly, with no flag saying the answer depended on the
machine's speed. When the clock does fire, the portfolio-wide deadline is reached and
`time_limit_reached` is true. Rust and the JavaScript fallback always run their starts against
the one portfolio deadline. Each start keeps its own counters against the whole budget in
Python, PHP and Rust; the JavaScript fallback hands each later start what the earlier ones
left of one budget, so the same number buys less search there.
the one portfolio deadline. Each start keeps its own counters against the whole budget, in all
four engines; until 1.9.0 the JavaScript fallback handed each later start what the earlier ones
left of one budget, so the same number bought less search there.

**Read `any_start_truncated` when the answer must not depend on the budget.** The selected
start can finish while another start, one that might have won, was stopped by the budget; the
Expand Down
36 changes: 36 additions & 0 deletions docs/UNITS-AND-NUMERICS.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,42 @@ a caller would get a number from one and a refusal from another for the same inp
carries the guarded sums in a representation that holds `10^30` exactly: Python's `int`,
PHP's `BigInt` decimal strings, JavaScript's `BigInt`, Rust's `i128`.

Areas follow the same rule in the search itself (1.9.0). Two lengths below
`PHP_INT_MAX` ticks multiply past a native `int` -- a 10 mm wide item longer than about
3,600 km already does -- and Python and Rust hold that product exactly. PHP forms every such
product (base and contact areas, their sums and the load shared by them, the centre-of-gravity
hull, lattice slot counts, the candidate score's room-left term) through
`Packvium\Support\ExactInteger` and `ExactGeometry`: the native `int` while it fits, an exact
decimal string past it, so an ordinary request pays one `is_int` check. The public
`Dimensions::baseAreaTicks()` and `AxisAlignedBox::overlapAreaXY()` keep their `int` contract.
`support_ratio` and `volume_utilization` are Python's correctly rounded `int / int`, not a
quotient of two doubles.

**The admission ceiling (1.9.0).** Every engine refuses, before any model is built, a
JSON request with a length past `2^53 - 1` ticks (about 563,000 km) or a box -- an item, a
container's inner or outer dimensions, an obstacle, a made-to-measure step -- enclosing more than
`10^30` cubic ticks (about 244 million cubic metres). Both are `invalid_request` with reason
`above_maximum` at the offending pointer (ERRORS.md). The first is the largest tick
count JavaScript's `Number` holds exactly; the second is the bound path's own ceiling, which keeps
`volume x 10^6` inside Rust's `i128`. Until 1.9.0 each engine failed past its own native limit: Rust
and PHP refused a length past `2^63 - 1` ticks with different errors, Python and JavaScript answered,
Python died with `decimal.InvalidOperation` at `10^20` mm, and Rust overflowed `i128` on a container
past about `1.7 x 10^32` cubic ticks. A whole JSON number past `2^53 - 1` is refused the
same way however a parser stored it, and a value past a native integer is read exactly to tell
which way it is out of range.

**Weights (1.9.0).** A weight is at most `2^63 - 1` ticks (about 1.15 million
tonnes), and so is every item's weight times its quantity plus the heaviest container tare, so
no container's payload or gross weight can pass a signed 64-bit integer, which is how Rust and
PHP add them. Past either, the request is `invalid_request` / `above_maximum`, at the weight or at
`/items`. A weight written as a JSON number past `2^53 - 1` is `invalid_value`: JavaScript has
rounded such a number before any engine code reads it, so a weight that large is written as a
string. Inside the ceiling every engine is exact: Python's `int`, PHP's `int` and `BigInt`,
Rust's `i64` with `i128` products, and in JavaScript a `BigInt` for every weight sum. A
JavaScript result carries a weight's `ticks`, and a `shipping_cost` score position, as a `Number`
while it is exact and as a `BigInt` past `2^53 - 1`; `stringifyExact` and `parseExact` move such
a result through JSON text without rounding it, and `pack` uses them on both backends.

That intermediate ceiling is deliberately not the result ceiling. The five bound keys can
cross JSON and are returned as JavaScript `Number` values, so every engine also refuses a
final key above **`2^53 - 1` (`9,007,199,254,740,991`)**. This is the largest integer all four
Expand Down
Loading
Loading