Repository navigation
Releases
Packvium 1.11.0
Bottom gussets and standing pouches, a certified bound for the shipping objectives, one money
ceiling, and one measure grammar.
Added
bottom_gusset_depthandorientationonDeformableBoundary::GussetedBag, with the new
BagOrientation { Flat, Standing }.Containergainsupright_frame. A struct literal or a
full pattern must name the new fields.optimality.lower_boundand the gap undershipping_costandlowest_landed_cost
(bounds.rs); the validator checks them.examples/checkout.rsandexamples/fulfilment.rs.
Changed
- One money ceiling, 2^53 − 1: a
rate_tablepriced above it at its top bracket is refused
at admission, and a quote refuses an amount above it where it used to answer up toi64::MAX
and wrap past it.RatingRejection::AmountOutOfRangebecameAmountAboveCeiling(i128). - Measures follow the shared grammar: upper-case units (
"1 G") are read;"100 millimeters"
and"1 -1/2"are refused;"-0 1/2"is minus a half, not plus.hull_verticesholds at most
32 points. effort_budgetlimits andtag_limitswritten as1000.0are the integers they equal.
Fixed
- A billed weight past
i64wrapped into the cheapest bracket, and an overflowing landed cost
was reported as a weight past the last bracket. - On wasm32, a JSON count of 2^32 truncated to 0 (
max_restarts,tag_limits). It now
saturates. - The result validator could panic sorting a crafted result with mixed-type values.
Performance
- The contact graph no longer buckets every box with the largest: 961,792 candidate checks
fall to 10,672 with one pallet-wide box among 4,000. - The safe-removal search is no longer cubic.
- The plan beam scores each plan 1.4–2.2 times less often.
- The exact search's visited set is capped at 262,144 states.
Packvium 1.10.0
Pallets may overhang their deck, mailers may have gussets, a hull turns 24 ways, every
placement has an id, a request may name its currency, and three more objectives state a lower
bound. Some public structs and enums grew, so a struct literal or an exhaustive match needs an
edit (see Changed); units refuses keys it used to ignore.
Added
container.pallet_overhang_limitis honoured, where 1.9 refused it: a load may pass the
deck by the stated length at each end and width at each side. Positions are measured from
the corner of the overhang zone; only the deck bears weight, so a floor placement's
support_ratiois the share of its base on the deck; the packed pallet reports
achieved_dimensionsand is billed and handed up at the larger of its declared footprint and
that size. Besideaccess_directions,axles,made_to_measure,obstacles, a non-zero
void_fill_reserve_ratioor an item'sstop_indexit isunsupported_feature. New types
OverhangLimitandDeck.- Gusseted bags:
deformable_boundary.kind: "gusseted_bag"withside_gusset_depth
admitsb + c <= W + G;DeformableBoundary::GussetedBag { side_gusset_depth }. - 24 rotations for a
convex_hullitem: 18 signed codes such as-L-W+Hafter the six
legacy ones, accepted only on a hull (on a box,invalid_value).Rotation::EVERY,
is_signed,is_upright,from_codeandvocabulary. placement_idon every placement, the canonical JSON of
[container id, x, y, z, item_type, orientation]in ticks.fixed_placements[]and a
revision's locked or verified placement may quote it;validate_jsonreports
placement_id_mismatchandduplicate_placement_id.currencyon the request and onrate_table, three capital letters, echoed on the
result; a rate table without a request currency or in another one isinvalid_request, and
validate_jsonreportscurrency_mismatch. It never enters the score.- Lower bounds for
maximum_value,open_dimension_heightandmaximum_volume, so
optimality.lower_boundand the gap are stated under every objective but the two carrier
ones. pack_nested_with(&request, level_beam_width)carries thekbest chains from level to
level and lets the outermost level choose; a width of 1 ispack_nested.- A made-to-measure box may keep a
void_fill_reserve_ratio; when the box cut tight
would break it, the box is cut from the envelope it was packed in. - Revisions stock the boxes a plan already cut: a locked or verified placement in a
made-to-measure box becomes a stock container<type>@<revision>#<n>at its cut size, and
verify_revision_chain_jsonreportsartifact_requiredwithout the approved artifact.
Newrevisions::stock_cut_boxes_json.
Changed
- Source change for struct literals and exhaustive matches.
PackingRequest,RateTable
andPackingResultgainedcurrency: Option<String>;FixedPlacementgained
placement_id: Option<String>;Containergainedpallet_overhang_limitanddeck;
DeformableBoundarygainedGussetedBag;Rotationgained 18 variants. None is
#[non_exhaustive]: add the fields to a struct literal (or build aContainerwith
..Container::new(...)), and give amatchoverRotationorDeformableBoundarya
wildcard arm. Callers ofpack_jsonare unaffected. unitsrefuses every key butlength:invalid_request/not_allowedat
/units/<key>. A request that sentunits.weightmust write the unit on each weight.- Every container is numbered per type on the grid lattice and the block loader too:
pair#1,large#1where 1.9 could saypair#2orlarge#10. - A nested chain keeps a handed-up container upright, so a nested answer can change where
laying a carton on its side was the only way it fitted. - Artifact exports refuse an integer past
2^53 - 1withnumber_out_of_range, instead of
clamping a container index.
Fixed
- An explicit rotation list emptied by
keep_uprightis refused atallowed_rotations,
with the same named request error the independent validator checks. - Stocking cut boxes indexes artifact lookups once and reports malformed consumed
machine fields as structuredinvalid_revisionerrors. - Nested beams keep fixed placements across container offers and handoffs instead of
aborting when a different carried branch cannot supply a locked item or container. - The standalone crate test suite handles absent workspace-only nested scenes; its
dedicated nested and fixed-lock regression tests still run.
Packvium 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). The centre of gravity is checked, and answers agree with the
other engines where 1.8 found them apart.
Changed
- Under a clearance a compressible item bears its load on its own footprint, so its crush
check is stricter andvalidatemeasures its own compressed volume. - A weight is at most
2^63 - 1ticks, 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 past2^53 - 1isinvalid_valueand must be a string. - The centre of gravity is checked under a
minimum_support_ratioabove 0: a placement
covering at most half its base with the centroid outside the contact hull is refused.
A request without a ratio packs as before. - 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 past2^53 - 1ticks or
a box past10^30cubic ticks isinvalid_request/above_maximum; a side that reads as zero
ticks isinvalid_value/must be positive; an obstacle box outside its container is
invalid_value/lies outside inner_dimensions, each at its own pointer. validatechecks 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.
exact_smallis 9-28% faster on the searches that run it (interned item ids, a child's
state key extended from its parent's); answers are identical.
Fixed
- A container past about
1.7 x 10^32cubic ticks overflowed; it is now refused at
admission, and a deep nesting column on the lattice no longer returns an answervalidate_json
refuses. - Null obstacle coordinates default to zero, including additional boxes, as request
admission already permits.
Packvium 1.8.0
Results now say how far they can be from the best possible answer, Optimal means a proof,
and a mistyped flag is refused instead of defaulted.
Added
optimality.lower_boundand the gap under thedefaultandlowest_costobjectives,
withbounds::for_request,from_items,statementandStatement;validate_json
checks them.
Changed
- Only attaining the bound sets
Optimal; a registry solver'sOptimalis demoted to
Feasiblefirst. - An effort budget names a stop: a run that ends on exactly its budget is
complete. - A non-boolean
keep_upright,stackable,must_be_on_flooror
require_placement_coordinatesisinvalid_request/wrong_type; it was read as the
field's default.
validate_jsonreturnsMalformedResult(contract) for such a request, and readsnullas
the default. - Faster with identical answers: loading-order checks about 3x,
exact_smallabout 2x on
larger requests (the preflight answer is reused instead of solved twice), axle-limited solves
up to 25%,rebalance_weightabout 18%.
Fixed
homogeneous_blocksnamed alone packs underfastandbalanced; it stopped before
its first block and placed nothing.validatereadsunits: nullandunits.length: nullas millimetres, as the engines do,
and refuses aunitsthat is not an object, or an unknownunits.length, as acontract
MalformedResultnaming the field.units.weightis not a field and is ignored: put the unit
on each weight.
Packvium 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)andvalidate_json_outcome, withResultIssue,
MalformedResult { kind, message }andRefusalKind: 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 orIndependentValidator, which is unchanged.PlacementConstraint::distinguishes_instances, a defaulted trait method,trueunless
overridden, so existing implementations compile and keep their behaviour. A constraint that
reads only item attributes may returnfalseto let the portfolio drop a start order that
repeats another's item-type sequence.
Changed
- A
CandidateScorerleads the extreme-point rank. The rank is the tuple (sum of
scorer scores, far corner z, y, x, origin, rotation); before, a scorer'sscorewas 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_ruleorconfiguration.solversisinvalid_requestwith reasonnot_allowed
at its JSON Pointer. An unknown output unit was copied through;ticksas an output unit is
now refused, as the schema always said. qualitylooks 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 reporttruncated/effort_limit.qualityfinishes 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. Withsolvers: ["extreme_points"]alone, over 67 benchmark
instances,fast/balanced/qualityleave 2711/1477/1297 items out instead of
3658/3048/2643. The full portfolio's answers did not change on the 89 benchmark requests, and
itsqualityCPU 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_containeris reportedproven, andinsufficient_supportis reported
(observed) where the support rule is the only blocker.- A
nesting_heightnot below the item's height is refused asinvalid_valueat its
pointer, and with nooutputblock the result is written inunits.length's schema code.
Fixed
incompatible_tagsis 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.
Packvium 1.6.0
Boxes cut to measure, flat bags, stacking groups and a volume-first objective, and a fix for
small orders with a convex_hull item that ran out the clock.
Added
EffortBudgetis re-exported from the crate root, andItem::new/Container::new
fill every other field with the value a JSON request gets when it omits it.MadeToMeasureandContainer::made_to_measure. An on-demand box machine (largest box,
minimum, cut step, board price and weight per m²); each packed box is the load's extent
rounded up onto the machine grid and priced as cut, reported by
PackedContainer::achieved_dimensions()and the result'smade_to_measure.DeformableBoundary::FlatBagandContainer::deformable_boundary. A poly mailer admits a
load when length plus thickness and width plus thickness fit.Item::stacking_groupandItem::accepts_stacking_groups. Which item classes may rest
directly on which.objective: "maximum_volume", ranking the volume left behind ahead of the piece count.- A warning for items resting on nothing when
minimum_support_ratiois 0. No answer
changes.
Code that builds Item or Container with a struct literal must add the new fields; None
and an empty set keep 1.5.0's behaviour.
Changed
- An unpacked item names the limit that left it out, the same in every engine.
Where the search used to fall back tono_feasible_placementorsearch_exhausted, an item a
fresh container would take but none is left reportscontainer_inventory_exhausted, and one
that overloads an axle wherever it stands alone reportsaxle_overloaded; both are
inferred. Code that matched the old reason for these cases must match the new one. - An explicit
solvers: ["homogeneous_blocks"]request packs in the profile's start order
when the block solver declines the scene, so the answer no longer depends on the
order the items are listed in. qualityorders its beam by aconvex_hullitem's own solid, not its box, so
it no longer assumes a second wedge cannot fit when it can.- The container plan counts a
convex_hullitem by its own solid too, so
qualityno longer ranks a plan as if wedges that share a container each needed their own. fastandbalancedadd the block solver as one more start and keep its answer only
when strictly better.
Fixed
- Small orders with a
convex_hullitem no longer run out the clock. The exact search
bounded a hull by its box volume, so it never stopped early: a five-item order with one jar
took the whole time limit and now takes 6 search nodes. The same bound left one of two
wedges that share a crate unpacked. Every release since 1.0.0.
Packvium 1.5.0
Every error names a closed code. A misspelt configuration key is now refused (see Fixed).
Added
pack_json_with(input, ExecutionOptions).pack_jsonwith explicit execution options;
ExecutionOptions { parallel: false }runs independent search starts in sequence. The
answer is the same either way.PackError::code()— the machine-readable code of every variant:invalid_input,
invalid_request,invalid_fixed_placement,unsupported_feature,unsupported_unit,
invalid_number,solution_failed_validation,time_limit. Branch on it instead of on the
message.PackError::request_error()— theRequestErrorbehindinvalid_requestand
invalid_fixed_placement, with itsreason()and JSON Pointerfield(), when there is one.
Changed
- Up to 41% faster on beam searches, same results. The collision index keeps its cells in a
flat array instead of a tree and sizes each query's result once. Measured: beam requests 41%
faster, a 60-item order 34%, a 250-item order 18%, peak memory within 4%. Every result is
byte-identical. pack_nestedchains levels. A level whose request lists no items packs the previous
level's containers, one item each; it is not run after a level that left something unpacked.
A level that lists its own items runs on them as before. A non-zerobeam_widthnow sets
every level'scontainer_plan_beam_width; it was ignored.
Fixed
qualitywithminimum_support_ratioanswers instead of failing. The homogeneous block
solver ran even when the request asked for support, and a block set on a smaller one
overhangs it, so the request ended insolution_failed_validation. Such a request is now
left to the per-item search. A block answer also reports the support each item really has;
it wrotesupport_ratio1.0 for every item.- A misspelt
configurationkey is refused. A key the request schema does not declare in
configurationor itseffort_budget(profileforsolver_profile,top_kfor
alternatives) was silently ignored, so the request ran on defaults.pack_jsonnow returns
PackError::InvalidRequestwith reasonnot_allowedand the key's pointer, for example
/configuration/profile.parallel, which this engine read although the schema never
declared it, is refused too; passExecutionOptions { parallel: false }topack_json_with
to run search starts in sequence. - An item that fits no orientation no longer spends the exact search's budget. One such
item made a scene solved in about 1 ms run to its whole budget (2.7 s andeffort_limitat
1M); it is now set aside before the search, which finishes in about 1 ms. Placements are
unchanged. - An unknown
objectiveor access direction is refused with its pointer (not_allowed),
and refusal messages match the documentation.
Packvium 1.4.0
Replanning a job that has already started, a beam search that no longer trades memory for
speed, and container ids that match the other engines.
Added
- Fixed placements.
fixed_placementsin a JSON request, or
PackingRequest.fixed_placementswithpackvium_core::FixedPlacement. Each entry pins an
item type to a container type and instance, at the origin a result reports, in one
orientation. Fixed items keep their place, count toward weight, support and top load, and
come back marked"fixed": true. A fixed set that is not a valid packing on its own is
refused withinvalid_fixed_placement: ...before any search. packvium_core::revisions—root_revision_json,derive_revision_json,
apply_events_json,verify_revision_chain_json,document_digest_jsonand
canonical_revision_json. Apackvium-plan-revision/v1chain records what happened on the
dock against the artifact it changed, linked by SHA-256, and carries the request the next
plan solves. Every Packvium engine computes the same bytes from the same inputs. Errors are
RevisionErrorwith aRevisionErrorCode.- A new dependency,
sha2(RustCrypto, no default features), for the digest. PackError::InvalidRequest(RequestError). A malformed request names what is wrong:
code()isinvalid_request,reason()one of a closed set (missing_field,wrong_type,
below_minimum,above_maximum,negative_measure,invalid_unit,duplicate_id,
not_allowed,invalid_value),field()the JSON Pointer of the bad value, and the message
readsinvalid_request: /items/0/quantity: must be at least 1. The fixed-placement refusal is
aRequestErrortoo, with codeinvalid_fixed_placement.examples/revisions.rs.
Changed
PackErroris#[non_exhaustive], and a malformed request isInvalidRequest. It used
to beInvalidInput,InvalidNumberorUnsupportedUnitwith free text. An exhaustive
matchonPackErrorneeds a wildcard arm; formatting the error is unaffected.- The container-plan beam keeps 1.3.0's speed without its memory cost. It ranks nodes by
five integers, compares placement signatures in place only when ranks tie, and orders only
the nodes it keeps. Results are byte-identical. At equal work it took 0.70× and 0.71× the
time of 1.3.0's, and peaked at 0.986× and 0.992× of 1.2.0's memory in a Linux container. - Container ids number each type from 1. The greedy and beam searches counted containers
across types, so a crate opened after a box wascrate#2where the other engines said
crate#1. Only answers with more than one container type change, and only their ids. PackingRequestgainsfixed_placementsandfixed_containers,Containergains
preloaded, andPlacementgainsfixed. JSON callers are unaffected. Code that builds
these structs with a literal must add the fields: empty vectors andfalsekeep 1.3.0's
behaviour.
Fixed
- Numbers below their floor are refused. A negative item or container quantity was
packed, and a zero or negativetime_limit_ms,max_containers,max_items,
alternatives, search width or rate-table amount was silently replaced by its default. Each
is now an error naming the field; an absent or null value keeps its default. - The independent validator checks incompatible tags. It had no
incompatible_itemsrule,
so an answer with incompatible items in one container passed it. The search already
enforced the rule, so only a hand-built answer or a fixed set could slip through. - A placement or obstacle far outside its container is refused. An origin near the top of
the integer range overflowed when its extent was added, and the box then looked inside. - A fixed placement is refused, never coerced, when it is not the schema's shape. An
instance of"1"or1.5, a position given as a list or null, or an unknown key is refused
naming the entry, instead of falling back to instance 1 or the origin.
Packvium 1.3.0
Portable operational artifacts for the Rust core, and execution plans that match the other
engines beyond the test corpus. Nothing breaks 1.2.0.
Added
packvium_core::artifacts::build_artifact_json(request_json, result_json, loading_orders_json)
builds onepackvium-operational-artifact/v1document: the execution plan, exact geometry,
the values a work order shows, and the request that produced it. Every Packvium
engine builds the same bytes from the same result. Errors areArtifactErrorwith an
ArtifactErrorCode.packvium_core::artifact_exports—export_json,export_csv(RFC 4180, 18 columns) and
export_work_order_html: a printable work order in one HTML file with no scripts and no
external resources.examples/artifacts.rs.
Fixed
execution::build_plan_jsondisagreed with the other engines on results outside the test
corpus. Score terms are now copied and compared by value, anullstatus is refused, a
nullloading order means no order and a non-integer entry is refused, and a missing
unplaced reason is written as the other engines write it. Floats are read exactly: the
default JSON parser could read one a step off and write different digits back.- The plan is written as RFC 8785, and a number beyond 2^53 − 1 is refused instead of written.
Changed
- The beam search caches its sort keys and the incumbent's key. Results are byte-identical.
On the wide cases measured (48 items, beam width 12) it took 18–26% less time for about
0.5 MB more resident memory. - A pinned catalog version resolves without scanning the version history.
Packvium 1.2.0
Execution plans for the Rust core, and a faster group-batching path. Nothing breaks 1.1.0.
Added
packvium_core::execution::build_plan_json(result_json, loading_orders_json)turns an
already validated result into a work order: what to lift, why a carton was chosen, and what
was not packed. It calls no solver and no validator. Solver decisions sit underfacts,
readable text underpresentation, and the step order is taken fromloading_ordersor
reported as"unavailable". The canonical JSON is byte-identical to the other Packvium engines.
Changed
- Group batching does less work. The extreme-point solver drops two quadratic scans over
group members for a single pass. Results are byte-identical.