00 — Overview
Demonstration prototype, simulation only. coast_11_portinterface is a reference application and part of the Coastal Shipping series (catalogue SHP-11, Stage 3). It holds no real cargo, vessel, customer, authority or terminal data and has no connection to any real port system: the transmission adapter, every authority response and every terminal notice are simulated.
What the Port & Terminal Electronic Interface is
Send the effective manifest to a port authority, record exactly what was sent, and record separately what the authority answered. It owns the submission, its cargo lines, every transmission attempt, the authority's acknowledgments, corrections, terminal notices, reconciliation and the authority's submission deadlines.
Four different things — kept apart
| Fact | Where | Meaning |
|---|---|---|
| Sent | TransmissionAttempt (outcome TRANSPORTED / TIMEOUT / AMBIGUOUS) |
the gateway took the message — nothing about the authority |
| Accepted / rejected / partial | PortAcknowledgment |
what the authority said, with its own response id, hash and authenticity |
| Uncertain | status UNCERTAIN | a timeout or ambiguous result: it may or may not have arrived; no resend until reconciled |
| Observed at a terminal | TerminalNotice |
an external observation; never a container movement (coast_03_tracking) or a tally (SHP-13) |
A submission is ACCEPTED only by an authentic acknowledgment from the authority for the payload that was sent — never by a delivery receipt, an operator's status or a simulated response on a live submission.
The rules the model is built around
- Positive cargo only. A submission carries the effective manifest snapshot from coast_02_manifest (the lines that remain after a correction's reversal and replacement are applied), as positive package counts. Reversal rows are the manifest's financial and revision history: they are never transmitted, and an effective cargo that contains one is refused.
- Drafts are prepared, never sent for you. When a manifest's effective cargo first arrives, a profile with
auto_preparegets a DRAFT; a newer revision proposes a correction with a replacement DRAFT. Validating, approving and sending are people's steps. - Current revision. A submission is built from, validated against, approved against and sent for the current effective revision; a newer revision makes an unsent submission stale (flagged, never sent).
- Load port call, not port. The submission names the explicit load port call (coast_06_voyage); it is inferred only when the voyage visits that port once, and a line mapped to another call blocks validation.
- Independent approval. A supervisor who did not prepare it approves a submission; a correction needs its own approved correction, by someone who neither proposed it nor prepared its replacement.
- Simulation only. Profiles default to SIMULATION; a LIVE profile needs a verified, non-mock format, a secret-store reference and a second person's authorisation — and this build has no live adapter, so nothing can be sent live.
- Uncertain means stop. A timeout, an ambiguous result or no response in time leaves the submission UNCERTAIN, raises an exception, and blocks any send of the same manifest until a person other than the sender settles it with the authority's retrieved response and evidence.
- Responses are never silently dropped or replaced. The same response id with the same hash is a replay (nothing changes); with another hash, or unauthentic, or for another payload, or for a submission never sent, it is quarantined with a reconciliation and an exception.
- Corrections keep the original. The accepted original, its attempts and its responses stay; it becomes SUPERSEDED only when the replacement is accepted.
- Closure is real. An exception for a rejected, partial or uncertain submission, a stale revision or an overdue deadline closes only when the domain correction is real (an accepted submission, a met or waived deadline).
- No credentials, no live payloads.
credential_refis a reference into the secret store; payloads aresimulation-store:labels; nothing sensitive is in an event. - Cross-application links are strings (
*_canonical_ref, with*_cid/*_refpairs). Every record has a hiddencanonical_ref.
The 13 models by area
| Area | Models |
|---|---|
| Submissions | PortSubmission · SubmissionCargo · TransmissionAttempt · PortAcknowledgment · PortCorrection |
| Terminal Notices | TerminalNotice |
| Reconciliation & Deadlines | PortInterfaceReconciliation · TransmissionDeadline · PortInterfaceException |
| Audit | PortInterfaceAudit |
| Profiles & Sources | PortInterfaceAuthority · PortInterfaceProfile · PortInterfaceSnapshot |
The pack's per-app outbox and inbox models were dropped (the integration runtime provides them); PortInterfaceException was added.
The demo scenario
The same story as the Stage 1 and 2 apps (voyage V26-014 ex Lae). PS-26-0001 sent manifest MF-26-014-LAE revision 1 to the demo port authority and the simulated authority accepted it. After the amendment AM-26-0001 (line 3 reversed, the excavator line added) PS-26-0002 carried revision 2's positive lines: the simulated send timed out (UNCERTAIN, not resent), a query showed the authority had rejected it, and the exception PX-0002 is still open. PS-26-0003 replaced it and was accepted, so PS-26-0001 is SUPERSEDED with its history intact; a late contradicting response is quarantined. Terminal notices TN-26-0001 and 0002 are validated observations, TN-26-0003 awaits validation, TN-26-0004 is a conflicting repeat held in quarantine. The V26-015 Lae deadline is open, with no manifest to send yet.