00 — Overview
Demonstration prototype. coast_14_demurrage is a reference application and part of the Coastal Shipping series (catalogue SHP-14, Stage 3). It holds no real cargo, container, customer, tariff or tax data — everything in the demo is fictional. Rates, free days and amounts are demonstration values; no universal tariff is asserted.
What the Storage, Demurrage & Detention Manager is
Calculate, from confirmed movements and a configurable policy, the charge for time — and hand billing one signed pre-tax entitlement per charge. It owns the charge policies, the exposures (a container held for one charge type between two confirmed movements), the approved suspensions and concessions, the immutable assessments and the signed entitlements.
Who owns what — and why the charge is never produced twice
| Fact | Owner | Meaning |
|---|---|---|
| Movement and custody, the gate fact | coast_03_tracking, coast_04_yard | what happened and when; this application only reads it as evidence |
| The pre-tax entitlement | this application | the days, the policy, the rate bands, the signed amount |
| Tax and the invoice or credit | coast_05_rating | prices the entitlement with the approved tax rule; reverses the ORIGINAL stored tax and total, never a recomputation |
| The ledger posting | the finance interface (Stage 3) | posts the issued document; this application never sees it |
An entitlement is sent once by canonical id and hash. A correction never edits it: the approved assessment is superseded, the exact reversal of the original entitlement and the replacement are published together.
The rules the model is built around
- Separate charge types, configurable by contract. Storage (terminal / yard), demurrage (container beyond free time on the quay) and detention (container outside the yard) have their own policies: start and end events, free days, how the start and end days count, overlap and the daily rate bands. The demo policies use local calendar days, start excluded, end included.
- Calendar days only, with an explicit timezone. A day is a local date in the policy's IANA timezone. Business-day and rolling-hour clocks are configurable but cannot be activated or calculated until a calendar and a tested adapter exist: there is no fallback.
- Confirmed evidence, not expected dates. A clock starts and stops only on a confirmed movement or gate record of the right container and event at the exact time. A missing, rejected, conflicting or untimed event blocks the final entitlement; a provisional as-of reading may be shown and is never approved.
- Free days before the tiers; suspensions once. Approved suspensions are inclusive local date ranges: a date inside several ranges is excluded once, and only eligible dates are excluded; the chargeable days never go below zero. Bands start at day 1, are contiguous and never overlap; a missing applicable band rejects the calculation.
- Pinned at the start. An exposure pins the policy (and so its terms and bands) that applied when it started; an active policy is frozen, a change is a new policy with a later
valid_from. - No overlap. The same container never has two exposures of one charge type over the same time; different charge types may overlap only when both policies say
ALLOW_CROSS_CHARGE. - Explicit concessions. Extra free days (before the bands) or an amount reduction (after), reasoned and approved by someone other than the proposer.
- Independent approval. The person who prepared a policy, a suspension, a concession or an assessment cannot approve it; the replacement of a correction is approved by a supervisor who did not calculate it.
- Immutable once published. A signed entitlement is never edited; the billing acknowledgement is the only way to ACCEPTED (a delivery receipt is not one), a conflicting hash is quarantined.
- Cross-application links are strings (
*_canonical_ref, with*_cid/*_refpairs). Every record has a hiddencanonical_ref.
The 13 models by area
| Area | Models |
|---|---|
| Exposures & Clocks | StorageExposure · StorageSuspension · StorageConcession |
| Assessments | StorageAssessment · StorageAssessmentBand |
| Entitlements & Billing | StorageEntitlement · StorageDispute · StorageBillingAck |
| Policies & Bands | StoragePolicy · StorageBand |
| Exceptions & Audit | StorageException · StorageAudit |
| Sources | StorageSourceSnapshot |
Model names are unique across the whole fleet (hence the Storage prefix). The pack's per-app outbox and inbox models were dropped (the integration runtime provides them).
The demo scenario
The Stage 1 story (voyage V26-014 ex Lae) continues at Port Moresby. EXP-26-0001 is the pack's worked example on DEMU1000001 (simulated evidence): 9 eligible days, 3 free, none suspended → 6 chargeable = 3 × 20.00 + 3 × 35.00 = PGK 165.00 ex tax (SA-26-0001, ENT-26-0001, accepted by billing; billing's mock 10% tax makes the invoice 181.50). The customer disputed it (DSP-26-0001, upheld): three suspended dates (4–6 Nov, two overlapping ranges counted once) → SA-26-0002, 3 chargeable = 60.00; ENT-26-0002 is the exact reversal (−165.00, credit of the original 181.50 including its stored 16.50 tax) and ENT-26-0003 the replacement (60.00 → billing's invoice 66.00; net adjustment −115.50), submitted and waiting for billing. EXP-26-0002 (storage) and EXP-26-0003 (demurrage) run on DEMU1000002 from its discharge at Port Moresby (allowed to overlap by both policies), with a provisional reading of 24.00 and a proposed goodwill concession. EXP-26-0004 is the container's empty trip out and back, inside its free days: nothing to charge.