DOCS / REFERENCE

Plan revisions and fixed placements

Replan a job already under way: loaded items stay put, and every change is recorded against the plan it changed.

Docs for Packvium 1.11.x · contract stable since 1.0

01Items already loaded stay where they are#

A request can carry fixed_placements: items already in a known place before the solve, loaded or locked there by an operator. Each entry names an item type, a container type and instance counted from 1, the position a result reports and one orientation, so a placement from an earlier result can be fixed by quoting it. The solve packs everything else around them. Python and PHP take FixedPlacement values in Packer.pack, Rust reads PackingRequest.fixed_placements, and every JSON entry point reads the field.

02A fixed item is a real placement#

Fixed items carry weight, support what is stacked on them, take top load and count against payload. They take the first instances of their item type, their containers open first and are always kept, and each comes back unmoved and marked fixed: true. The independent validator refuses an answer that moves one.

04A revision records what happened on the dock#

A plan revision is an append-only, hash-chained record of what differed from an approved plan: an item missing, a container substituted, a placement locked by an operator or verified in place. The events are applied to the request, not to the result, and each revision carries the request the next plan solves, with locks and verified placements carried as fixed placements. It names its parent revision and the operational artifact it was recorded against by SHA-256 over their RFC 8785 bytes, orders events by sequence rather than by a clock, and calls no solver, validator or clock, so every engine computes the same revision bytes from the same inputs.

loaded = pack_from_dict(copy.deepcopy(root["request"]))["containers"][0]["placements"][0]
events = [
    {"sequence": 1, "type": "placement_locked", "placement": {
        "item_type": "cube", "container_type": "tote", "container_instance": 1,
        "position": {axis: loaded["position"][axis]["value"] for axis in ("x", "y", "z")},
        "orientation": loaded["orientation"]}},
    {"sequence": 2, "type": "item_missing", "item_type": "slab", "quantity": 1},
]
revision = derive_revision(root, approved, events)

05The replan is an ordinary solve#

Nothing is remembered from the first solve: the replan packs the revision's request under the normal portfolio and the normal validator. Two engines may still reach different, equally valid packings of it, and the artifact each approves then describes its own. The revision records the replay level of the plan it was recorded against, and a plan a clock stopped is not guaranteed to replay, which is why the packages' own example bounds its search by counted work rather than by time.

06An audit that does not stop at the first problem#

Verifying a chain reports every way it fails to be what its root and events derive: revision_number, parent_mismatch, sequence_gap, request_mismatch and artifact_mismatch. A revision whose request was edited after the fact is reported as request_mismatch, because it no longer equals what its parent and events produce. An event that contradicts the request, such as a missing pallet that was never requested, is refused by name as event_conflict rather than applied as a best guess, and the other refusals are invalid_revision, invalid_event, invalid_artifact and the canonical-form codes.

07One surface per language#

Python: packvium.revisions, with root_revision, derive_revision, verify_revision_chain, document_digest and canonical_revision_json. PHP: Packvium\Revisions\PlanRevision, with root, derive, verifyChain, digest, canonicalJson and parse. Rust: packvium_core::revisions, the same functions over JSON. JavaScript: @packvium/engine/revisions.js. Revisions, FixedPlacement and the fixed-placement error are in the frozen API. Python also ships packvium.revision_outcomes, which is supported but not yet frozen.