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/native-bridge 1.8.0 (PHP)"
placeholder: "packvium/native-bridge 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/native-bridge 1.8.0 (PHP)"
placeholder: "packvium/native-bridge 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
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ jobs:
matrix:
php: ["7.4", "8.0", "8.1", "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 All @@ -44,7 +44,7 @@ jobs:
test-with-ffi:
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 All @@ -69,7 +69,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 @@ -54,7 +54,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
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ What changed in `packvium/native-bridge` on Packagist, release by release. The f
[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 changes of its own. Both backends, `packvium/packvium` 1.9.0 and the 1.9.0 C library, now
check the centre of gravity under a support ratio, refuse a length past `2^53 - 1` ticks or an
empty side with a pointer, and agree on nesting under a clearance.

## [1.8.0]

No changes of its own. Both backends, `packvium/packvium` 1.8.0 and the 1.8.0 C library,
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-bridge"
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,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 @@ -159,7 +159,7 @@ CodeMeta form.
@software{packvium_php_bridge,
author = {{Packvium contributors}},
title = {Packvium native bridge 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 native bridge for PHP",
"description": "Packvium backend bridge: the Rust engine over FFI when available, pure PHP otherwise.",
"version": "1.8.0",
"version": "1.9.0",
"license": "https://spdx.org/licenses/MIT",
"author": [
{
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