01 — Quick Reference

Group Models
Exposures & Clocks StorageExposure · StorageSuspension · StorageConcession
Assessments StorageAssessment · StorageAssessmentBand
Entitlements & Billing StorageEntitlement · StorageDispute · StorageBillingAck
Policies & Bands StoragePolicy · StorageBand
Exceptions & Audit StorageException · StorageAudit
Sources StorageSourceSnapshot

Every model (13) — one line each

Model It records Key foreign keys
StoragePolicy A charge policy: type, port, start and end events, free days, clock basis and timezone, day counting, overlap, currency, validity, priority; frozen once ACTIVE —
StorageBand A daily rate band (chargeable day first..last); frozen with its policy StoragePolicy
StorageExposure One container held for one charge type from a confirmed start to a confirmed end; pins its policy StoragePolicy
StorageSuspension An approved inclusive range of local dates when the clock is paused StorageExposure
StorageConcession Extra free days or an amount reduction, reasoned and independently approved StorageExposure
StorageAssessment One version of the calculation: clock and rate snapshots, days, amount, hash; immutable once calculated StorageExposure, itself (previous)
StorageAssessmentBand The chargeable days that fell in one band, at its rate StorageAssessment, StorageBand
StorageEntitlement The signed pre-tax amount published to billing once (CHARGE, REVERSAL, REPLACEMENT); immutable StorageExposure, StorageAssessment, itself (original)
StorageDispute A dispute of a published entitlement; never edits it StorageEntitlement
StorageBillingAck Billing's durable acknowledgement (ACCEPTED, REJECTED, CONFLICT) and the invoice detail; append-only StorageEntitlement
StorageAudit Who did what, append-only —
StorageException A control exception: missing / conflicting / rejected evidence, overlapping exposure, disputed rate, billing conflict or mismatch StorageExposure, StorageEntitlement
StorageSourceSnapshot What other applications told us (movements, gate records, billing documents): stored once, hashed —

Workflows

Record Transitions (guard)
StoragePolicy DRAFT → ACTIVE (supervisor other than the preparer; valid bands; CALENDAR_DAY only; no equal-priority twin) → RETIRED
StorageExposure OPEN → ENDED (confirmed_end_event) → RECONCILED (movement_evidence_complete: physical times, no rejected or conflicting evidence, no open clock dispute)
StorageAssessment DRAFT → CALCULATED (policy_valid, clock_valid) → APPROVED (closed_period_or_authorised_interim, independent_approval; creates the entitlement) → SUPERSEDED (approved_reversal_and_replacement; publishes the exact reversal and the replacement)
StorageEntitlement APPROVED → SUBMITTED (unique_source_hash; publishes storage.entitlement_approved) → ACCEPTED (durable_billing_source_ack) or REJECTED (billing_rejection)
StorageSuspension / StorageConcession PROPOSED → APPROVED or REJECTED (supervisor other than the proposer)
StorageDispute OPEN → UPHELD or REJECTED (supervisor other than the one who raised it)

Vocabularies

  • StoragePolicy.charge_type: STORAGE · DEMURRAGE · DETENTION (clock_basis CALENDAR_DAY · BUSINESS_DAY · ROLLING_HOUR — only the first is implemented; overlap_policy NO_OVERLAP · ALLOW_CROSS_CHARGE; status DRAFT · ACTIVE · RETIRED)
  • StoragePolicy.start_event / end_event: GATE_IN · GATE_OUT · LOAD · DISCHARGE · PACK · UNPACK · TRANSFER
  • StorageExposure.status: OPEN · ENDED · RECONCILED
  • StorageAssessment.status: DRAFT · CALCULATED · APPROVED · SUPERSEDED
  • StorageEntitlement.status: APPROVED · SUBMITTED · ACCEPTED · REJECTED (entitlement_kind CHARGE · REVERSAL · REPLACEMENT)
  • StorageBillingAck.status: ACCEPTED · REJECTED · CONFLICT
  • StorageSourceSnapshot.status: CURRENT · SUPERSEDED · CONFLICT · REJECTED (time_basis PAYLOAD · ENVELOPE)
  • StorageException.exception_type: MISSING_EVIDENCE · INCONSISTENT_EVIDENCE · EVIDENCE_REJECTED · OVERLAPPING_EXPOSURE · DISPUTED_RATE · BILLING_CONFLICT · BILLING_REJECTED · BILLING_MISMATCH · OTHER (control codes STORAGE_CLOCK_DISPUTE, STORAGE_BILLING_MISMATCH)

Messages (network member)
Commands accepted none (the pack gives this application no commands)
Events published storage.entitlement_approved (on submit, once per entitlement id and hash) · storage.exception_raised · storage.exception_resolved
Events consumed yard.gate_recorded · tracking.movement_accepted · tracking.movement_rejected · rating.billing_document_issued (observation only) · rating.entitlement_acknowledged · rating.supplemental_detail_issued · assurance.action_requested

Run, seed, regenerate

python server/run.py coast_14_demurrage                    # http://localhost:5198
python -m codegen.cli all coast_14_demurrage               # regenerate models, controllers and JSON after a schema change
python -m codegen.cli seed coast_14_demurrage --reset      # reload the sample data
python -m codegen.cli integration coast_14_demurrage       # regenerate the integration package (handlers.py is never overwritten)
python scripts/build_diagram_viewer.py coast_14_demurrage  # rebuild the interactive diagram