00 — Overview

Demonstration prototype. coast_10_release is a reference application and part of the Coastal Shipping series (catalogue SHP-10, Stage 2). It holds no real cargo, container, customer or customs data — everything in the demo is fictional. The documents are prototype templates: not negotiable titles and not customs forms.

What the Shipping Documentation & Cargo Release Manager is

Decide, commercially, who may take which cargo — and keep that decision safe until the yard acts on it. It owns shipping document versions, the release request with its checks and holds, the release authority per quantity, and the short-lived exclusive quantity reservations the yard takes immediately before an outward gate.

Three different things — kept apart

A commercial release is confirmed only when the yard has recorded the gate fact, this application has consumed the reservation once, and tracking has accepted the movement.

The rules the model is built around

• Fail closed. A missing, pending, failed, expired or stale check means no release. Billing issue is not payment: freight release needs positive evidence. Customs is evidenced by hand until the Stage 3 customs interface; a not applicable customs or quarantine check needs a reason and a different approver.
• Entitlement. Quantities cannot exceed the effective cargo of the manifest; the same entitlement is never released twice (per container or cargo item); partial release is normal.
• Exclusive, short-lived reservation. The yard reserves a quantity against the current authority version; refused if the authority is not active, its version or validity is wrong, a hold is active, the container differs, or quantity > authorised − consumed − reserved (the pack's validate_reservation arithmetic).
• The clock alone never frees a reservation. An elapsed reservation stays held, a sweep raises one exception, and only the yard's durable no-movement attestation releases the quantity.
• Consumed once. The matching gate fact consumes the reservation exactly once. A late or conflicting fact (after expiry, another gate fact, wrong container or quantity) never erases the gate: the reservation goes to EXCEPTION, keeps its quantity, and an exception is raised for people (and assurance) to reconcile.
• Holds and corrections. An active hold or a manifest correction suspends the unconsumed authority and blocks new reservations; consumed quantities and physical facts are never reversed. Fresh checks and a new document version are needed before the authority resumes.
• Documents. Issued versions are immutable; a correction issues a new version that supersedes the old; approval is by someone other than the preparer.
• Cross-application links are strings (*_canonical_ref, with *_cid / *_ref pairs). Every record has a hidden canonical_ref.

The 15 models by area

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

The demo scenario

The same story as the Stage 1 apps (voyage V26-014 ex Lae). REL-26-0001 releases CN-26-0001 (10 pallets in DEMU1000002 at Port Moresby): all checks current, authority RA-26-0001; 4 pallets consumed (RSV-26-0001), 2 returned after the yard attested no movement (RSV-26-0002), 3 held by a reservation that expired with no gate fact and no attestation (RSV-26-0003, exception RX-0001). REL-26-0002 (Madang, freight collect) fails closed on the unpaid freight. REL-26-0003 (the plant item) has its authority suspended by the manifest correction AM-26-0001; its bill of lading v1 is superseded by v2.