00 — Overview
Demonstration prototype. coast_12_customs is a reference application and part of the Coastal Shipping series (catalogue SHP-12, Stage 3). It holds no real cargo, customs, broker or authority data — everything in the demo is fictional, and the customs authority adapter is a SIMULATION. Nothing here is a customs declaration, a tariff classification or legal advice.
What the Customs & Border Clearance Interface is
Know whether customs applies to this cargo, what the authority decided, which holds stand — and give the commercial release a straight answer. It owns the customs applicability of a movement, the broker mandate, the declaration with its immutable item snapshot, the transmission to the (simulated) authority adapter, the official decisions, the regulatory holds, and the current clearance position per consignment scope.
Four different things — kept apart
| Fact | Owner | Meaning |
|---|---|---|
| Customs clearance / hold | this application | what the authority decided, for which scope and manifest revision, and whether a hold stands |
| Commercial release | coast_10_release | the permission to release cargo; it asks this application for a live check |
| Physical gate fact | coast_04_yard | what actually left the yard (a late hold never erases it) |
| Container custody and tracking hold | coast_03_tracking | where the container is; it applies its own scoped hold from customs.hold_changed |
The rules the model is built around
- Applicability is explicit. Every movement is IMPORT, EXPORT, TRANSIT or COASTAL. A domestic coastal shipment is not automatically subject to an international declaration, and it is not presumed cleared: it needs an explicit NOT_REQUIRED assessment with a reason, evidence and an approver who is not the assessor. With none, a live check answers UNKNOWN.
- Classification is separate. The customs HS code is entered by a person with evidence; it is never taken from the commercial freight commodity code or class (those are only kept for reference).
- Acceptance is not clearance. An accepted declaration has no CLEARED assessment. Clearing needs a VERIFIED clearance decision for the exact scope and manifest revision, still valid, with no active hold.
- Only an authorised, current clearance counts. The live check compares the exact revision, the covering scope, the validity, the decision and the mode; missing, held, revoked, stale, pending, simulated or scope-mismatched answers are never positive.
release_authorisedis the pack'srelease_clearancepredicate. - Simulation cannot authorise a live release. A SIMULATION profile makes SIMULATED transmissions and SIMULATION results; its clearances answer
release_authorised: false. - Independent approval and verification. The preparer cannot approve a declaration; the recorder of an official result cannot verify it; the requester cannot approve an amendment; the assessor cannot approve a not-required determination. An unmatched, unauthenticated or mismatched result is QUARANTINED.
- A hold overlaps by scope. A verified hold turns every overlapping clearance into HELD, holds the declaration and raises an exception; physical facts already recorded are never touched. A lift applies only to the matching hold (a verified lift naming that hold, in the same mode) and never restores a clearance by itself: reinstating needs every hold lifted and a current verified clearance.
- A submitted revision is immutable. An amendment is a new linked version (an approved amendment, then the replacement; superseding the prior needs the replacement CLEARED).
- Assessments are versioned and immutable. A new version supersedes the old one; a newer manifest revision or an elapsed validity turns a standing clearance STALE (the sweep and the effective-cargo event publish it).
- No cross-app foreign keys. Cross-application links are strings (
*_canonical_ref, with*_cid/*_refpairs). Every record has a hiddencanonical_ref.
The 15 models by area
| Area | Models |
|---|---|
| Declarations | CustomsDeclaration · DeclarationItem · CustomsDocument · CustomsTransmission · DeclarationAmendment |
| Decisions & Holds | CustomsDecision · RegulatoryHold |
| Current Clearance | ClearanceAssessment · CustomsClearanceCheck · CustomsException |
| Audit | CustomsAudit |
| Profiles & Sources | CustomsAuthority · ClearanceProfile · BrokerMandate · CustomsExternalSnapshot |
Model names are unique across the whole fleet. The pack's 15 models are all here except the per-app outbox and inbox (the integration runtime provides them); CustomsException and CustomsClearanceCheck are additions (see the README).
The demo scenario
The same story as the other coastal apps (voyage V26-014 ex Lae, manifest MF-26-014-LAE at revision 2). CN-26-0001 and CN-26-0003 are domestic COASTAL consignments with an explicit NOT_REQUIRED assessment (CA-26-0001 / 0002, LIVE, independently approved); a live check authorises them. CN-26-0002 has no assessment yet: a live check answers UNKNOWN until someone determines applicability. A separate, fictional import case (pack scenario S3-03), CN-IMP-26-0001 on manifest MF-IMP-26-001 revision 2: declaration DECL-26-0001 was prepared, validated, approved, submitted (a SIMULATED transmission), accepted (acceptance is not clearance), cleared by a verified clearance, then a late inspection hold (RH-26-0001, line 1) turned it HELD: assessment CA-26-0005 HELD is current, exception CUX-0001 is open, and a check is refused. DECL-26-0002 is a draft whose item has no HS classification yet; an amendment of DECL-26-0001 (customs value) waits for approval.