diff --git a/.github/DISCUSSION_TEMPLATE/ideas.yml b/.github/DISCUSSION_TEMPLATE/ideas.yml new file mode 100644 index 0000000..4a0c3aa --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/ideas.yml @@ -0,0 +1,28 @@ +title: "[Idea] " +labels: ["idea"] +body: + - type: markdown + attributes: + value: | + Ideas for new packing rules, outputs or integrations. An idea the maintainers take on + is moved to an issue and linked back here, so you can follow it. + - type: textarea + id: problem + attributes: + label: The problem behind the idea + description: What real shipment or load does today's library not handle? + validations: + required: true + - type: textarea + id: idea + attributes: + label: The idea + validations: + required: true + - type: input + id: package + attributes: + label: Package(s) you use + placeholder: "packvium-native" + validations: + required: false diff --git a/.github/DISCUSSION_TEMPLATE/q-a.yml b/.github/DISCUSSION_TEMPLATE/q-a.yml new file mode 100644 index 0000000..37ec047 --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/q-a.yml @@ -0,0 +1,30 @@ +title: "[Q&A] " +labels: ["question"] +body: + - type: markdown + attributes: + value: | + Ask anything about using the library. If you have found a wrong result or an error, + a bug report is the better place. + - type: input + id: package-version + attributes: + label: Package and version + placeholder: "packvium-native 1.8.0 (Python)" + validations: + required: true + - type: textarea + id: question + attributes: + label: Your question + description: What you are trying to pack, and what you tried. + validations: + required: true + - type: textarea + id: request + attributes: + label: Request (optional) + description: The JSON request or code, if it helps. + render: json + validations: + required: false diff --git a/.github/DISCUSSION_TEMPLATE/show-and-tell.yml b/.github/DISCUSSION_TEMPLATE/show-and-tell.yml new file mode 100644 index 0000000..2f06fbb --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/show-and-tell.yml @@ -0,0 +1,33 @@ +title: "[Show and tell] " +labels: ["show-and-tell"] +body: + - type: markdown + attributes: + value: | + Using the library in a shop, a warehouse tool or a load planner? Tell us how. Leave out + anything confidential about your business. + - type: textarea + id: what + attributes: + label: What you built + validations: + required: true + - type: input + id: package-version + attributes: + label: Package and version + placeholder: "packvium-native 1.8.0 (Python)" + validations: + required: false + - type: textarea + id: lessons + attributes: + label: What worked, and what got in the way + validations: + required: false + - type: input + id: link + attributes: + label: Link (optional) + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..89b5651 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,105 @@ +name: Bug report +description: A result that is wrong, an error you did not expect, or a crash. +title: "[Bug]: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting. A report we can run is a report we can fix, so the most useful + thing below is the smallest request that shows the problem. + + **Security problems do not belong here.** Use **Report a vulnerability** under the + Security tab instead; it opens a private advisory. + - type: dropdown + id: package + attributes: + label: Package + description: Which package did you call? + options: + - "packvium (PyPI) — Packvium for Python" + - "packvium-native (PyPI) — Packvium native backend selector for Python" + - "packvium/packvium (Packagist) — Packvium for PHP" + - "packvium/native-bridge (Packagist) — Packvium native bridge for PHP" + - "@packvium/engine (npm) — Packvium for Node.js" + - "@packvium/browser (npm) — Packvium for browsers" + - "packvium (crates.io) — Packvium for Rust" + - "packvium-native-rust (PyPI) — Packvium native engines: Python wheels, Node addons and the C library" + - Not sure + default: 1 + validations: + required: true + - type: input + id: version + attributes: + label: Package version + description: The exact version installed, for example 1.8.0. + placeholder: "1.8.0" + validations: + required: true + - type: input + id: runtime + attributes: + label: Runtime and operating system + description: Language runtime version and OS, for example "Python 3.12, Ubuntu 24.04" or "PHP 8.3, macOS 15". + validations: + required: true + - type: dropdown + id: profile + attributes: + label: Search profile + options: + - fast + - balanced + - quality + - exact_small + - Not set / default + - Not sure + validations: + required: false + - type: textarea + id: request + attributes: + label: Request that reproduces it + description: | + The JSON request, or the code that builds it, cut down as far as it still shows the + problem. Remove anything confidential; renamed item ids are fine. + render: json + validations: + required: true + - type: textarea + id: actual + attributes: + label: What happened + description: The result (or its relevant part), or the full error message and stack trace. + render: text + validations: + required: true + - type: textarea + id: expected + attributes: + label: What you expected + description: What the result should have been, and why. If another of the packages gives a different answer for the same request, say which. + validations: + required: true + - type: dropdown + id: stopped-by + attributes: + label: How was the search limited? + description: A search stopped by a time limit can differ between runs by design; one stopped by an effort budget cannot. + options: + - effort_budget + - time_limit_ms + - Both + - Neither / not sure + validations: + required: false + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I searched the existing issues and did not find this one. + required: true + - label: I read [docs/GUARANTEES.md](https://github.com/toxakara/packvium-python-adapter/blob/HEAD/docs/GUARANTEES.md) and this is not something it says the library does not guarantee. + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..70a081d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Question or help with a request + url: https://github.com/toxakara/packvium-python-adapter/discussions/categories/q-a + about: Ask in Discussions → Q&A. Answers there help the next person too. + - name: Report a security vulnerability + url: https://github.com/toxakara/packvium-python-adapter/security/advisories/new + about: Report privately. Do not open a public issue for a security problem. + - name: Documentation + url: https://packvium.com/docs + about: Guides, the request contract and the constraint reference. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..f86809b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,62 @@ +name: Feature request +description: A packing rule, constraint, output or integration the library does not support yet. +title: "[Feature]: " +labels: ["enhancement", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Open-ended ideas are welcome in **Discussions → Ideas** first. Use this form when you can + describe a concrete problem the library does not solve today. + - type: dropdown + id: package + attributes: + label: Package you use + options: + - "packvium (PyPI) — Packvium for Python" + - "packvium-native (PyPI) — Packvium native backend selector for Python" + - "packvium/packvium (Packagist) — Packvium for PHP" + - "packvium/native-bridge (Packagist) — Packvium native bridge for PHP" + - "@packvium/engine (npm) — Packvium for Node.js" + - "@packvium/browser (npm) — Packvium for browsers" + - "packvium (crates.io) — Packvium for Rust" + - "packvium-native-rust (PyPI) — Packvium native engines: Python wheels, Node addons and the C library" + - More than one + default: 1 + validations: + required: true + - type: input + id: version + attributes: + label: Package version + placeholder: "1.8.0" + validations: + required: true + - type: textarea + id: problem + attributes: + label: The problem + description: What are you packing, into what, and what rule or output is missing? A real (anonymised) example helps more than a general description. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: What you would like + description: The behaviour or field you have in mind, if you have one. + validations: + required: false + - type: textarea + id: workaround + attributes: + label: What you do today + description: Any workaround you use, and what it costs you. + validations: + required: false + - type: markdown + attributes: + value: | + Every package implements one shared contract, so a new rule or result field lands in all + of them together, and a change to the request or result format waits for a release that + is allowed to change it. A request that is accepted may therefore take more than one + release to ship. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2ed9a58..ee57988 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,7 +15,8 @@ jobs: strategy: fail-fast: false matrix: - os: [ubuntu-latest, macos-latest, windows-latest] + # ubuntu-24.04, not ubuntu-latest: ubuntu-latest became 26.04, which setup-python has no 3.9 for. + os: [ubuntu-24.04, macos-latest, windows-latest] python: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"] steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 diff --git a/.github/workflows/rc.yml b/.github/workflows/rc.yml new file mode 100644 index 0000000..7f8277c --- /dev/null +++ b/.github/workflows/rc.yml @@ -0,0 +1,83 @@ +name: rc + +# A pre-release tag (`v1.9.0-rc.1`) builds and tests exactly as `release.yml` does, then goes +# to TestPyPI -- a separate index whose database "may be periodically pruned" -- and never to +# PyPI, where a version is permanent. There is no GitHub Release: an RC is not a release. +# +# Before the first RC, once (the owner): +# 1. Create an account on https://test.pypi.org (separate from the PyPI one) and enable 2FA. +# 2. Add a pending Trusted Publisher for project `packvium-native`: owner `toxakara`, repository +# `packvium-python-adapter`, workflow `rc.yml`, environment `testpypi`. +# 3. In this repository, create a GitHub environment named `testpypi` with the same +# reviewers as `pypi`. +# 4. Set the repository variable RC_PUBLISHING to `enabled`. +# `packvium-native` is not on production PyPI yet (DEFERRED in the workspace's publication +# check); an RC on TestPyPI is the only index it can reach until that publisher exists. +# A consumer then installs it with +# pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ packvium-native== + +on: + push: + tags: ["v*-*"] + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: "3.12" + - run: python -m pip install --upgrade pip build twine + - run: python -m build + - run: python -m twine check --strict dist/* + + # The tag and the packaged version must agree. Without this, `git tag v0.2.0` on a + # tree that still says 0.1.0 publishes 0.1.0 under a name that claims otherwise, + # and the mistake is only visible after it is public and immutable. + - name: The tag must match the version in the distribution + run: | + tagged="${GITHUB_REF_NAME#v}" + built=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])") + if [ "$tagged" != "$built" ]; then + echo "tag $GITHUB_REF_NAME does not match pyproject version $built" >&2 + exit 1 + fi + + - name: Install the built wheel into a clean environment and re-run the tests + run: | + python -m venv /tmp/clean + /tmp/clean/bin/python -m pip install --quiet pytest packvium + /tmp/clean/bin/python -m pip install --quiet --no-index --find-links dist packvium-native + /tmp/clean/bin/python -m pytest tests -q + + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: distributions + path: dist/ + + # Inert until the owner sets the repository variable RC_PUBLISHING to `enabled` (Settings -> + # Secrets and variables -> Actions -> Variables). Without it the job is skipped and the run + # stays green, so an RC tag pushed before the accounts exist publishes nothing. + publish-testpypi: + needs: build + if: vars.RC_PUBLISHING == 'enabled' + runs-on: ubuntu-latest + environment: testpypi + permissions: + id-token: write # OIDC, for Trusted Publishing and for the attestation + attestations: write # build provenance, so a consumer can verify where a file came from + steps: + - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8 + with: + name: distributions + path: dist/ + - uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1 + with: + subject-path: dist/* + - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2 + with: + repository-url: https://test.pypi.org/legacy/ diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 563a449..f7a0dee 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,9 +12,11 @@ name: release # and create a GitHub environment named `pypi` with whatever reviewers the project # wants. +# A pre-release tag (`v1.9.0-rc.1`) never reaches the production registries: the negated +# pattern must follow the positive one, and `rc.yml` takes those tags instead. on: push: - tags: ["v*"] + tags: ["v*", "!v*-*"] permissions: contents: read diff --git a/CHANGELOG.md b/CHANGELOG.md index 3076c68..7790a9a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ What changed in `packvium-native` (Python), release by release. The format follo [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.8.0] + +No changes of its own; the `native` extra is pinned to `packvium-native-rust==1.8.0`. Neither +this package nor that one is on PyPI yet, so use +[`packvium`](https://pypi.org/project/packvium/) directly. + ## [1.7.0] The native path now raises what the pure engine raises (see *Fixed*). diff --git a/CITATION.cff b/CITATION.cff index 9b3e935..da4c96b 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -5,7 +5,7 @@ type: software authors: - name: "Packvium contributors" website: "https://packvium.com" -version: "1.7.0" +version: "1.8.0" license: MIT url: "https://packvium.com" repository-code: "https://github.com/toxakara/packvium-python-adapter" @@ -22,3 +22,5 @@ keywords: - packing-algorithm - logistics - deterministic + - box-packing + - load-planning diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 788addd..8bff4dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,3 +39,24 @@ wrong, not a documented quirk. Please include the full request that reproduces it and `backend()`'s return value at the time. For anything with security implications, follow [SECURITY.md](SECURITY.md) rather than opening a public issue. + +## How your feedback is handled + +Every issue and discussion is read by a maintainer. This is what happens next: + +1. **New issues are labelled `needs-triage`.** A maintainer answers with one of: a question + back to you, a confirmation, or a reason it will not be taken on. +2. **A confirmed bug** gets the `bug` label and is reproduced from your request. A wrong result + in one package is checked against the others, because all of them implement the same + contract and must agree. +3. **An accepted feature request or idea** is added to the project's backlog, and the issue is + labelled `accepted` with a comment saying so. An idea from Discussions is first turned into + an issue and linked back to the discussion. +4. **When the change ships**, the issue is closed with the release it shipped in. A change to + the request or result format can only ship in a release that is allowed to change it, so + it may take more than one release. +5. **Declined** requests are closed with the reason, so you are never left waiting on a + silent issue. + +Questions go to **Discussions → Q&A**; security problems go to **Report a vulnerability** +under the Security tab, never to a public issue. diff --git a/README.md b/README.md index 6b85366..038cd01 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,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.7"` | [packvium-rust](https://github.com/toxakara/packvium-rust) | +| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.8"` | [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) | @@ -106,7 +106,7 @@ CodeMeta form. @software{packvium_python_adapter, author = {{Packvium contributors}}, title = {Packvium native backend selector for Python}, - version = {1.7.0}, + version = {1.8.0}, license = {MIT}, url = {https://packvium.com} } diff --git a/codemeta.json b/codemeta.json index be92547..8ceea92 100644 --- a/codemeta.json +++ b/codemeta.json @@ -3,7 +3,7 @@ "@type": "SoftwareSourceCode", "name": "Packvium native backend selector for Python", "description": "Packvium backend selector: the native engine when a wheel is available, pure Python otherwise.", - "version": "1.7.0", + "version": "1.8.0", "license": "https://spdx.org/licenses/MIT", "author": [ { @@ -26,6 +26,8 @@ "truck-loading", "packing-algorithm", "logistics", - "deterministic" + "deterministic", + "box-packing", + "load-planning" ] } diff --git a/docs/GUARANTEES.md b/docs/GUARANTEES.md index e0949d9..8cdcba6 100644 --- a/docs/GUARANTEES.md +++ b/docs/GUARANTEES.md @@ -14,8 +14,11 @@ After a result reports `feasible` or `optimal` and passes independent validation - **exact arithmetic** — all geometry is integer, in units of 1/16000 mm for length and 1/8 µg for weight. No coordinate is ever a binary floating-point number, so no placement decision depends on rounding; -- **determinism** — identical input and identical seed produce an identical result, on - any platform, when the search completes or stops on `configuration.effort_budget`. A +- **determinism** — for a fixed backend and version, identical input and seed produce + identical packing and deterministic diagnostics on supported platforms when the search + completes or stops on `configuration.effort_budget`. Wall-clock timing diagnostics, + such as `duration_ms` and `elapsed_ms`, are excluded. This does not promise identical + solutions between backends; their documented native quality differences remain. A search stopped by `time_limit_ms` stops where the host's speed let it, so it may differ between runs; the result says which limit stopped it; - **complete accounting** — every requested item instance appears exactly once, either @@ -24,9 +27,15 @@ After a result reports `feasible` or `optimal` and passes independent validation ## It does not guarantee - **A globally optimal packing.** The `fast`, `balanced` and `quality` profiles are - heuristic. Only `exact_small`, within its item limit, searches exhaustively — and even - then optimality is not certified in the result. A returned solution is a good solution, - not a proven best one. + heuristic, and `exact_small` searches exhaustively only within its item limit. A returned + solution is a good solution, not a proven best one, unless the result proves it: under the + `default` and `lowest_cost` objectives a result states `optimality.lower_bound`, and a + complete result whose score attains that bound reports `optimal` / `proven_optimal`. That + proves no packing obeying the request's rules scores better on that objective; it says + nothing about a rule the request cannot express. Any other stated result carries the gap + to the bound, an upper limit on what a longer search could still gain. The statement is + withheld if its gap exceeds the portable integer ceiling of `2^53 - 1`, even when the + request's bound fits. Where geometry makes a request hard, expect a gap. - **Physical safety in transit.** Nothing here models vibration, shock, acceleration, tipping, strapping or load shifting. A geometrically valid packing can still be an unsafe shipment. @@ -52,7 +61,7 @@ silently — if you need them, they belong in your own layer above this library. ## Status of this release -Version `1.7.0` freezes the public API. Field names, status codes, the objective +Version `1.8.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. diff --git a/docs/PUBLIC-API.md b/docs/PUBLIC-API.md index fa05074..0f4fa85 100644 --- a/docs/PUBLIC-API.md +++ b/docs/PUBLIC-API.md @@ -155,10 +155,16 @@ request field. - `termination.code`: `complete`, `time_limit`, `effort_limit`, or `error`; - `optimality.code`: `proven_optimal`, `proven_infeasible`, `best_found`, or `not_proven`. The 1.1.0 freeze reserved and typed `gap_key`, `absolute_gap` and `relative_gap` - alongside it. The pre-1.1.0 extension point remains open: closing the object would - make a previously valid producer fail a 1.1.0 validator, which is a breaking change - and therefore not legal in this minor release. No engine emits the reserved fields - yet, so `code` is still the only key any Packvium result carries; + alongside it, and the 1.8.0 freeze added `lower_bound`: the lower bound on + `score`, in the result's own score order, through the first position the result misses + -- or all of it when none is missed, which proves the result optimal for its objective + under the rules this library models. `gap_key` requires `lower_bound`, and absence of + `lower_bound` makes no statement at all; it is never "attained". The pre-1.1.0 + extension point remains open: closing the object would make a previously valid + producer fail a validator, which is a breaking change. Every engine emits these fields + since, on the primary result and on each alternative, for the `default` and + `lowest_cost` objectives; a complete result that attains its bound reports `status: + optimal` and `code: proven_optimal`, and nothing else does; - legacy `status`: `optimal`, `feasible`, `best_found`, `time_limit`, `infeasible`, or `invalid_result`; - packed containers with exact coordinates, dimensions, rotations, and a `centre_of_mass_offset_ppm` — the weighted centre of mass's exact-integer Chebyshev @@ -238,7 +244,10 @@ objective vector. `algorithm.time_limit_reached` and `algorithm.effort_limit_reached` identify distinct, mutually exclusive causes. The former is only a wall-clock deadline. The latter means -one of the request's counted-work boundaries was reached. An unpacked `time_limit` or +the selected start was stopped by one of the request's counted-work boundaries: the search +had more work to do and the budget refused it. A start that finished having used exactly its +budget was not stopped, and reports neither flag. No counter in `algorithm.metrics` ends +above its limit: each counted step is checked before it is taken. An unpacked `time_limit` or `effort_limit` reason must match the corresponding flag. ## Loading and unloading sequences @@ -401,8 +410,9 @@ deadline: Each fact is an open object with a required string `code`. Consumers must preserve an unknown code and any additional fields, allowing future effort/node/cancellation limits without turning a minor release into a parsing break. `status` remains for one -compatibility cycle and is checked against the three facts. The alpha release emits no -`proven_optimal` claim without a future proof/certificate. +compatibility cycle and is checked against the three facts. `proven_optimal` is emitted only +on a complete result whose score attains its stated `optimality.lower_bound`: a proof that no +packing obeying the request's rules scores better on the result's own objective. `status: infeasible`, with `feasibility: infeasible` and `optimality: proven_infeasible`, is emitted only when the portfolio ranks no result at all. A request whose every item is proven @@ -452,6 +462,23 @@ The fields answer separate questions: | `winning_start_truncated` | The selected packing itself came from an interrupted start. | | `global_deadline_reached` | The portfolio-wide deadline expired, independently of individual start slices. | +**Under an `effort_budget` the clock is the request's fuse, and fires only as a whole.** +Without one, Python and PHP give each start an even share of the time left, so one slow start +cannot starve the rest. With one, every start may use all the time left: a request that +bounds its work by counting must get the same answer on any machine, and a start cut by its +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. + +**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 +top-level flags then read `complete`, because they describe the selected start. +`any_start_truncated` is the only field that says a larger budget could change the answer. A +checkout that caches a quote refuses one on it (ECOMMERCE-CHECKOUT-INTEGRATIONS.md D3). + The aggregate fields are derived only from `starts`. Exactly one record is selected. `completed` and `truncated` are mutually exclusive and both require `started`. `termination.code` is `time_limit` when the selected start or portfolio hit the wall @@ -526,9 +553,10 @@ valid. A result without the documented shape is refused as `MalformedResult`, wh same as one JSON document for a binding. - PyO3 (`packvium_native_rust`): `validate_json(request, result)` over JSON text, a list of `{"code", "detail"}` dicts, `MalformedResult` (a `ValueError`) with `kind`. -- `@packvium/engine`: `validate(request, result)`, `MalformedResult`, and - `ValidatorUnavailableError` (`code: 'validator_unavailable'`) when the compiled addon is - absent, until the JavaScript fallback's port. +- `@packvium/engine`: `validate(request, result)` and `MalformedResult`; the compiled addon + answers when it is loaded and the package's JavaScript port otherwise (1.8.0). + `ValidatorUnavailableError` (`code: 'validator_unavailable'`) is still exported but + deprecated: nothing throws it since 1.8.0. - `@packvium/browser`: `validate(request, result)`, a promise, `MalformedResult`. - PHP: `Packvium\Validation\validate(array $request, array $result)`, a `list` @@ -727,3 +755,11 @@ depend on the exact shape. Python, PHP, Rust and the JavaScript fallback accept the same top-level keys: `units`, `configuration`, `items`, `containers`, `catalog_versions_used`, `policy`, `output` and `fixed_placements`. + +`units` holds one key, `length`: the unit of every length written without one, millimetres when +`units`, or `units.length`, is absent or `null`. There is no request-wide weight unit. A weight +takes its unit from the measure itself (`"2.5 kg"`, `{"value": "2.5", "unit": "kg"}`), and a +bare number is grams. `units.weight` is not a field: today every engine ignores it without an +error, so `{"length": "cm", "weight": "kg"}` still reads a bare weight `2` as 2 g. Write the unit +on each weight instead. A future release that changes the request schema will refuse unknown +keys in `units`, as it already refuses them in `configuration`. diff --git a/pyproject.toml b/pyproject.toml index e47b11e..aefa26e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta" [project] name = "packvium-native" -version = "1.7.0" +version = "1.8.0" requires-python = ">=3.9" description = "Packvium backend selector: the native engine when a wheel is available, pure Python otherwise." readme = "README.md" license = "MIT" -keywords = ["3d-bin-packing", "bin-packing", "3d-packing", "cartonization", "container-loading", "pallet-packing", "truck-loading", "packing-algorithm", "logistics", "deterministic"] +keywords = ["3d-bin-packing", "bin-packing", "3d-packing", "cartonization", "container-loading", "pallet-packing", "truck-loading", "packing-algorithm", "logistics", "deterministic", "box-packing", "load-planning"] authors = [{name = "Packvium contributors"}] dependencies = [] @@ -31,7 +31,7 @@ test = ["pytest", "packvium; python_version >= '3.10'"] # wheel too, rather than requiring a second, separate install command. Pinned to this # release, which `scripts/suite_version.py` keeps in step: a wheel from another release # answers with that release's rules while this selector claims its own. -native = ["packvium-native-rust==1.7.0"] +native = ["packvium-native-rust==1.8.0"] [tool.setuptools.packages.find] where = ["src"] diff --git a/src/packvium_native/__init__.py b/src/packvium_native/__init__.py index 45ba5bf..f0d186e 100644 --- a/src/packvium_native/__init__.py +++ b/src/packvium_native/__init__.py @@ -4,7 +4,7 @@ from types import ModuleType from typing import Any, Optional -__version__ = "1.7.0" +__version__ = "1.8.0" #: Each untyped model error's code and the prefix the core's `PackError` writes before its #: detail (`packvium-core` `error.rs`). `packvium` reports a model it cannot build as reason