UK Trade Quota Balance & Status Change Signals

Turn the official daily UK trade-quota dataset into compact, filterable change-intelligence signals. This Actor is for monitoring, analytics, and change intelligence only. It is not real-time quota availability, customs-declaration eligibility, guaranteed remaining quota, guaranteed duty treatment, or operational import-decision support. HMRC allocations can take several days to appear in the published balance; always use the official operational channels for customs decisions.

Source and identity

The source is the Department for Business and Trade Data API report uk-trade-quotas / quotas-including-current-volumes, derived from UK Tariff and HM Revenue & Customs data and normally updated daily. Every live run resolves latest once, extracts the immutable vX.Y.Z identifier, and uses only that pinned version for metadata and CSV requests. quota_definition__sid is the identity of a quota definition/quota period. A quota order number can have many periods and is deliberately not the entity key. Order numbers stay strings; cosmetic leading-zero differences do not produce a signal.

The Actor stores only quota-level regulatory/trade fields needed for comparisons. It does not ingest personal data or metadata contacts. #NA, blank, and null values become null; a missing balance never becomes zero. Multi-value scopes are Unicode-normalized, trimmed, deduplicated, and sorted so source ordering alone cannot trigger a signal. Fill rate is the official source value and is not recalculated or reinterpreted.

Signals

• NEW_QUOTA_PERIOD — a SID newly appears in the official full dataset; it does not claim a new legal scheme or operational availability.
• QUOTA_STATUS_CHANGED — the official status string changed. The Actor never infers Exhausted, Closed, or availability from balance.
• BALANCE_DECREASED / BALANCE_INCREASED — the official balance changed; no duplicate generic event is emitted.
• FILL_RATE_CHANGED, LAST_ALLOCATION_DATE_CHANGED, VALIDITY_PERIOD_CHANGED.
• COMMODITY_SCOPE_CHANGED, GEOGRAPHICAL_SCOPE_CHANGED, and INITIAL_VOLUME_CHANGED.

SID disappearance is not a business signal. Because the source includes historical quotas, excessive disappearance is treated as a source anomaly and blocks output and snapshot replacement.

Safe state lifecycle

Live processing is: resolve latest → pin immutable version → fetch and validate OGL metadata → fetch CSV → schema and anomaly validation → normalization and stable-key validation → load previous snapshot → diff and filter → Dataset → OUTPUT summary → snapshot commit. Snapshot commit is last; Dataset or OUTPUT write failures retain the previous good snapshot.

On a fresh key-value store, the full validated snapshot is saved, Dataset stays empty, signalsFound and signalsEmitted are zero, and the summary says BASELINE_INITIALIZED. Re-running the same version/state emits nothing. maxItems limits Dataset items only; snapshots are always complete. The summary records the pinned version, release header, bytes, SHA-256, row/entity counts, SID profile, signal counts, and snapshot information.

Guards reject HTML/error payloads, malformed CSV, missing required columns, invalid finite numbers, null SIDs, conflicting duplicate SIDs, unexpectedly small files/row sets, a 30%+ row collapse, and implausible SID disappearance. Exact duplicate SID rows may collapse. Source-side staleness is reported through the pinned release timestamp rather than misrepresented as an Actor failure.

Input and sample mode

Filters include signal types, quota order numbers, official statuses, commodity codes, geographical areas, minimum absolute balance change, and minimum fill-rate change. baselineOnly refreshes a validated baseline without signals.

mode: "sample" is the free demonstration path and the Console prefill. It performs no HTTP request, never opens or mutates the production named key-value store, uses deterministic fixtures through the production normalize/diff/filter path, covers every core signal, writes a non-empty Dataset, and returns snapshotUpdated: false.

Licence, attribution, and privacy

The pinned version CSVW metadata identifies the Open Government Licence v3.0, which permits copying, publication, distribution, adaptation, and commercial use subject to its terms and exemptions. Contains public sector information licensed under the Open Government Licence v3.0. Source: Department for Business and Trade / HM Revenue & Customs UK trade quotas.

The product processes quota-level public data, not personal data (PRIVACY_MINIMISATION_PASS). Known limitations are the source publication cadence, possible HMRC allocation lag, upstream corrections, and the fact that output describes published changes rather than legal or operational advice.