Replan when the dock does not match the plan
Record what happened on the dock against the approved plan, then replan the rest around what is already loaded, with a tamper-evident history.
Wherever a plan is approved ahead of time and reality changes it: a nightly load plan, a pallet that does not arrive, a truck swapped for another one.
- 01
rootRevision() records the approved request; the plan is built from it and approved.
- 02
On the dock, events are recorded against that plan: a placement locked in place, an item missing, a container substituted.
- 03
deriveRevision() applies the events to the request: loaded items become fixed placements, missing ones leave the item list.
- 04
pack() solves the derived request as an ordinary request; nothing already on board moves, and verifyRevisionChain() audits the history.
import { pack } from '@packvium/engine';
import { buildOperationalArtifact } from '@packvium/engine/artifacts.js';
import { deriveRevision, rootRevision, verifyRevisionChain } from '@packvium/engine/revisions.js';
// Tonight's plan for tomorrow's first truck, approved and stored with its revision.
const root = rootRevision({
items: [
{ id: 'pallet-a', quantity: 2, weight: '400 kg', dimensions: { length: '1200', width: '800', height: '1200' } },
{ id: 'pallet-b', quantity: 3, weight: '250 kg', dimensions: { length: '1200', width: '800', height: '1000' } },
],
containers: [
{ id: 'truck', quantity: 1, max_payload: '12000 kg', inner_dimensions: { length: '7200', width: '2450', height: '2600' } },
],
});
const plan = pack(structuredClone(root.request));
const approved = buildOperationalArtifact(root.request, plan);
const first = plan.containers[0].placements[0];
// Morning, on the dock: the first pallet is already on board, one pallet-b never arrived.
const events = [
{ sequence: 1, type: 'placement_locked', placement: {
item_type: first.item_type, container_type: 'truck', container_instance: 1,
placement_id: first.placement_id, // 1.10: the id every engine derives alike
position: { x: first.position.x.value, y: first.position.y.value, z: first.position.z.value },
orientation: first.orientation,
} },
{ sequence: 2, type: 'item_missing', item_type: 'pallet-b', quantity: 1 },
];
const revision = deriveRevision(root, approved, events);
// Replan what is left around what is already loaded; nothing on board moves.
const replanned = pack(structuredClone(revision.request));
const kept = replanned.containers[0].placements.filter((placement) => placement.fixed).length;
console.log('placed', replanned.summary.packed_item_count, 'of which kept in place', kept);
// Store the chain; an audit later recomputes every link and flags any edit.
console.log('chain issues:', verifyRevisionChain([root, revision], [null, approved]).length);Five pallets were planned. After one is locked on board and one never arrives, the replan places the four that are left and keeps the loaded one exactly where it stands; the revision chain verifies with no issues.
Every program on these pages is run exactly as printed by this site's test suite, against the published package, on every change.
Every revision: it names its parent and the plan it replaces by SHA-256 over canonical bytes, so the chain shows who changed what and in which order, and an edited revision no longer verifies.
An event that contradicts the request - a missing pallet that was never requested - is refused as PlanRevisionError with a code, not applied as a best guess. If what is left no longer fits around the fixed items, the replan names those items in unpacked_items like any other answer.
npm install @packvium/engine