Coastal Shipping 13 — Cargo Handling & Stevedoring Manager (coast_13_stevedoring)
What was expected, what was physically counted, and what the difference means — handling plans from the effective manifest, shifts, tally facts with signed corrections, handling activity with its equipment and time, operational discrepancies and the physical reconciliation of a call.
Its central question:
Did the cargo that the manifest says should be handled at this port call actually go over the quay — in the same unit, container by container — and is every difference explained with evidence?
coast_13_stevedoring is application SHP-13 of the Coastal Shipping series (coast_NN_<name>, numbered by the pack catalogue; each able to run stand-alone or as a member of a network, Stage 3). It shares no tables and no foreign keys with its siblings
(for example coast_02_manifest, whose effective cargo it plans from, coast_06_voyage, whose calls it handles, coast_03_tracking, which alone owns container movements, or coast_08_portcosts, which alone approves a supplier handling cost) —
they link by canonical_ref strings and by messages. All data is fictional.
The spine
HandlingPlan → HandlingInstruction (expected) / HandlingShift → HandlingTally (physical) → HandlingTallyCorrection / HandlingDiscrepancy → HandlingReconciliation, with HandlingActivity (equipment and time), HandlingException and HandlingAudit around it.
The documents
| Page | What's in it |
|---|---|
| 00 — Overview | What the app is, expected versus physical, the rules, the 13 models, the demo scenario |
| 01 — Quick Reference | Menu map, every model, status vocabularies, the messages, how to run, seed and regenerate |
| 02 — System Diagram | The data model as diagrams (+ interactive viewer) and how the app links to its siblings |
Status
Built (workflow and guards, tested): plan approve / start / reconcile / close with independent approval, a frozen approved snapshot, revised instructions instead of edits, a safe operating authorisation and an independent review; positive tallies with the unit and scope of their instruction (no mass, volume or TEU conversion); independent verification; immutable verified tallies; signed correction with a positive replacement, published once and never counted twice; shortage, overlanded, damaged and unidentified cargo as discrepancies with evidence, resolution and follow-up references; handling activity with equipment in service and a current inspection, verified independently and published for supplier invoice matching; the reconciliation with its expected and actual hashes; the app's own control exception (HANDLING_DISCREPANCY, plan on an older manifest, call no longer valid); versioned projections of the effective cargo, voyage, call and call mapping; container movements and terminal notices as evidence only.
Tests: server/tests/integration_apps/test_coast_13_stevedoring_rules.py, _handlers.py, _display.py and the pack cross-check server/tests/test_coast_13_pack_crosscheck.py (the tally variance equals the pack's calculations/stage3_reference.py).
Not built yet / simulated: no command exists in the pack to ask coast_02_manifest for an amendment or coast_03_tracking for an investigation — a discrepancy only records the reference of a request made elsewhere. The call owner's own completion check (coast_06_voyage) is not consumed back. Terminal-notice types are stored and noted but not interpreted. The pack's real wire formats, credentials and endpoints do not exist: the terminal notice is an input from the simulated port interface (coast_11_portinterface).
Translation decisions (pack → native DSL)
| Pack | Here | Why |
|---|---|---|
S841 … S851, S854 |
HandlingProvider, HandlingPlan, HandlingInstruction, HandlingShift, HandlingEquipment, HandlingTally (pack CargoTally), HandlingTallyCorrection, HandlingActivity, HandlingDiscrepancy (pack CargoDiscrepancy), HandlingReconciliation, HandlingAudit, HandlingSourceSnapshot (pack ExternalSnapshot) |
fleet-unique names |
S852_OutboxEvent, S853_InboxMessage |
dropped | the integration runtime provides them |
canonical_id |
canonical_ref (every model) + cid on the network entities |
series rule |
voyage_ref, port_call_ref, manifest_ref, cargo_line_ref, consignment_ref, container_ref (strings of other applications) |
*_canonical_ref + *_cid + readable *_ref |
as coast_10_release; events publish the canonical string under the pack's name and the readable one beside it (call_ref, manifest_line_ref, container_number, plan_no) |
version |
version_no |
|
occurred_at in tally_verified |
tally_occurred_at |
occurred_at is an envelope field |
| shipping.control.exception_detected / assurance.action_completed | handling.exception_raised / handling.exception_resolved (+ HandlingException) |
the app's own control exception, as every Stage 1 and 2 app |
| shipping.handling.tally_verified.v1 / activity_verified / reconciled | handling.tally_verified / handling.activity_verified / handling.reconciled |
<domain>.<name>, one dot |
| shipping.manifest.effective_cargo / voyage.snapshot / portcall.snapshot / voyage.cargo_call_mapped / container.movement_accepted / portinterface.terminal_notice | manifest.effective_cargo, voyage.snapshot, voyage.portcall_snapshot, voyage.cargo_call_mapped, tracking.movement_accepted, portinterface.terminal_notice |
names of the producing apps |
| (added) | on plan: prepared_by, approved_by, snapshot_hash, safe_operating_*, started_*, closed_*; on instruction: revision_no, supersedes_id; on tally: snapshot columns, recorded_by, verified_by, signed_quantity, event_ref, original_tally_ref, source_hash; on discrepancy: variance_quantity, resolution_type, follow_up, follow_up_ref; on reconciliation: summary_json, evidence_ref |
independent-approval guards, immutable plan snapshot, revised instructions and the signed correction facts need somewhere to live |
HandlingReconciliation.revision_no |
the manifest revision the plan was reconciled against (the effective revision known, never lower than the plan's) | the pack's revision_no of handling.reconciled |
pack workflow correct guard approved_linked_replacement |
an APPROVED correction (HandlingTallyCorrection) whose positive replacement is a recorded tally of the same plan, instruction, line, direction, unit and container |
|
signed_reversal_quantity, reversal_event_ref |
the reversal is exactly the negative of the original; the reference is assigned by the system (what is typed is replaced) | the reversal is unique and names its original |
Deviations from the pack's wording: the pack's current_manifest and valid_port_call guards need the manifest and call projections: when none has been received (a stand-alone instance) the plan is checked against what was typed; once the effective cargo is known the guard fails closed
(wrong revision, a line that is not on it, a line without a call mapping or mapped to another call, a call that is cancelled, departed or of another voyage). A SHORT is recorded once the last shift has closed (an OVER at once), because a count in progress is not short.