00 — Overview

Demonstration prototype. coast_13_stevedoring is a reference application and part of the Coastal Shipping series (catalogue SHP-13, Stage 3). It holds no real cargo, container, customer or equipment data — everything in the demo is fictional. A tally is an operational fact: not a container movement and not a financial posting.

What the Cargo Handling & Stevedoring Manager is

Keep what was expected apart from what was physically counted, and explain every difference. It owns the handling plan of one operation at one port call (planned from the effective manifest and the call mapping), the shifts, the tally facts, signed corrections of a verified tally, the handling activity with its equipment and time, the operational discrepancies and the physical reconciliation of the call.

Four different things — kept apart

The rules the model is built around

• Expected and physical are separate. A shortage, an overlanded pallet or damage is an operational discrepancy with evidence and a HANDLING_DISCREPANCY control exception. It never changes the manifest, a container movement or a financial record by itself; it can only refer to an amendment request, a tracking investigation or an assurance case made elsewhere.
• Same unit, same scope. A tally is compared with its instruction by cargo line, container, direction and unit. Packages, containers, TEU, mass and volume are never converted into each other (tally_variance, equal to the pack's reference function).
• Plan from the effective manifest and the call mapping. The approved plan is a frozen snapshot (its hash); a cargo change makes a revised instruction that supersedes the old one, never an edit and never a deleted physical fact.
• Independent people. The approver is not the preparer; the safe operating authorisation comes from someone else; a tally, an activity and a correction are verified or approved by someone other than who recorded them; the plan's review is not the preparer or the reconciler.
• Corrections are signed. A verified tally is never edited: a correction is the exact negative of the original (published once, naming the original) plus a positive replacement, which is verified only after the original is corrected, so a quantity is never counted twice. Never a manifest or financial reversal.
• Completion needs resolution. A plan reconciles only when every tally is verified, every shift closed, every activity verified, no correction pending and every discrepancy resolved or formally accepted with evidence. The reconciliation carries the expected and actual hashes; the call owner (coast_06_voyage) validates completion.
• Equipment. Crane and heavy-lift activity needs equipment in service with a current inspection.
• Cross-application links are strings (*_canonical_ref, with *_cid / *_ref pairs). Every record has a hidden canonical_ref.

The 13 models by area

Model names are unique across the whole fleet (hence the Handling prefix). The pack's per-app outbox and inbox models were dropped (the integration runtime provides them).

The demo scenario

The same story as the other apps (voyage V26-014 ex Lae). HP-26-0001 (Lae load, on manifest revision 1) is tallied 10 + 14 + 1 packages, reconciled MATCHED and closed. HP-26-0002 (Port Moresby discharge) was approved on revision 1; revision 2 replaced the plant item, so its instruction was revised (HI-26-0005 superseded by HI-26-0006); a first count of 8 was reversed by a signed correction (HC-26-0001) and replaced by 9, one damaged pallet is an accepted DAMAGED discrepancy, the crane hours and handling are verified activity for the supplier invoice matching, and the plan is reconciled MATCHED waiting for its independent review. HP-26-0003 (Madang discharge) is active: 13 of 14 packages verified — one pallet SHORT (HD-26-0002, exception HX-0003 open, the consignee's claim) — a pallet with no instruction waits for verification and an activity for its verifier. HP-26-0004 (V26-015 Lae load) is a draft.