USDA Global Commodity Forecast Revision Signals

Monitor official USDA Foreign Agricultural Service (FAS) Production, Supply and Distribution (PSD) data and emit structured revision bundles when previously accepted forecast values change.

This Actor is intended for agricultural commodity analysts, procurement and supply-chain teams, market-intelligence workflows, banks/insurers, researchers, and agents that need machine-readable USDA forecast revisions. It is not a price-prediction service, trading recommendation, WASDE text scraper, historical-release-vintage reconstruction service, or financial advice.

Official source

Production acquisition uses only the official credential-free USDA FAS PSD SOAP service:

https://apps.fas.usda.gov/PSDExternalAPIService/svcPSD_AMIS.asmx

V1 uses getDatabyCommodityPerYear, which returns the available countries and attributes for one requested commodity code and market year.

The legacy PSD Online REST lookup endpoints are not a production dependency. Empirical runtime testing returned 403 "Bad API Key", so V1 does not require those endpoints, an API.Data.Gov key, private lookup caches, or third-party mirrors.

What one paid signal means

V1 has exactly one business signal type:

FORECAST_REVISION

One paid Dataset item represents one changed:

commodity × country × marketYear

bundle for one observed semantic transition.

If Production, Exports, and Ending Stocks all change in the same bundle in one accepted source cycle, they appear together in one changes[] array and still produce one Dataset item. There is no additional charge per changed attribute.

Stable source identity

The raw PSD row identity is:

CommodityCode + CountryCode + MarketYear + AttributeId

Value is the mutable monitored field and is not part of identity.

UnitId, CalendarYear, and Month are semantic guard fields, not identity fields. Empirical preflight profiling covered Corn, Wheat, and Soybeans across three populated market years each: 9 commodity-year datasets and 15,381 source rows with zero stable-key duplicates, zero null key fields, and zero null/non-finite values.

First live run is a silent baseline

The first valid run for a unique monitor scope:

1. acquires every requested commodity/year SOAP slice;
2. validates and normalizes the complete source cycle;
3. validates optional country/attribute filters against that acquired scope;
4. stores the accepted monitor snapshot;
5. emits zero business signals.

Existing PSD values are not replayed as historical revisions. This Actor only guarantees revisions observed after that monitor's first accepted baseline.

Explicit monitor scope

Live inputs are:

• commodityCodes[] — required, strings, maximum 10; leading zeros are preserved;
• marketYears[] — required, explicit 4-digit years, maximum 6;
• countryCodes[] — optional;
• attributeIds[] — optional integer IDs;
• maxItems — output cap only.

Market years never roll automatically with the calendar. Changing commodity/year/country/attribute scope creates a new monitor fingerprint and therefore a new silent baseline. Changing only maxItems keeps the same monitor identity.

Country and attribute filter validation

Optional country and attribute filters are validated against the official PSD rows returned for the commodity/year scope of the current live run. A requested filter value that is absent from that scope causes the run to fail rather than being silently ignored.

This is scope-membership validation. The Actor does not claim to maintain a global USDA country-code or attribute registry.

All requested commodity/year slices are acquired successfully before country/attribute filter validation begins. Partial source success is never used to generate revisions.

Revision semantics

For an existing raw row, only a value change can create a forecast revision.

For every changed attribute, the signal includes:

• rowKey
• attributeId
• attributeName
• unitId
• unitDescription
• before
• after
• delta
• direction (RAISED or CUT)

The signal ID is deterministic from the monitor fingerprint, bundle identity, sorted changed row keys, and before/after values. Detection time is not part of the signal ID.

New rows are not paid events

A raw PSD row that appears after baseline is accepted silently into the next snapshot.

V1 is a revision monitor, not a new-series monitor. A newly appearing row therefore creates no paid Dataset item. Later value changes to that accepted row can produce normal FORECAST_REVISION signals.

Fail-closed anomaly handling

Previously accepted row disappears

If a previously accepted raw row is missing from the next fully acquired monitor scope, the Actor does not interpret that as forecast removal.

It fails closed as:

SOURCE_ROW_DISAPPEARANCE_ANOMALY

with:

• business signals = 0
• accepted snapshot mutation = 0

This protects against partial or structurally changed official responses.

Semantic guard field changes

For the same raw row key, a change to any of:

• UnitId
• CalendarYear
• Month

fails closed as:

SOURCE_SEMANTIC_ANOMALY

The old and new numeric values are not compared as a forecast revision, and accepted state remains unchanged.

Description-only changes (commodityName, countryName, attributeName, unitDescription) do not create paid signals. Updated descriptions can be accepted silently when IDs and semantic guard fields remain stable.

Atomic source cycle

A live run must acquire and validate every requested commodity/year SOAP slice before comparison.

The Actor fails closed without accepted-state mutation on, among other conditions:

• official HTTP/network failure;
• unexpected authentication requirement;
• empty/unsupported requested commodity-year;
• SOAP fault or parse failure;
• unexpected source host/path or content type;
• missing canonical field;
• source commodity/year mismatch;
• duplicate stable key;
• null/non-finite value;
• previously accepted row disappearance;
• semantic guard-field change;
• partial acquisition.

No revisions are emitted from a partially acquired source cycle.

Pending queue and maxItems

maxItems limits Dataset emission only.

If 80 revision bundles are detected and maxItems is 30, the first 30 deterministic queued events are emitted and the remaining 50 stay pending in monitor state. Pending events drain before newly detected events.

Pending identity is the deterministic signalId, not merely the commodity/country/year bundle. If the same bundle is revised again before an older pending transition is delivered, both distinct transitions are preserved when their signal IDs differ.

The accepted source snapshot may advance after successful Dataset + OUTPUT writes while undelivered signals remain pending.

State-commit safety

State is committed last:

1. Dataset signals;
2. OUTPUT summary;
3. compressed monitor state.

If Dataset or OUTPUT persistence fails, accepted monitor state is not committed.

Example live input

{
  "mode": "live",
  "commodityCodes": ["0440000"],
  "marketYears": [2026],
  "countryCodes": ["BR", "US"],
  "attributeIds": [28, 88],
  "maxItems": 30
}

The specific codes and IDs above are an input-format example; users should select the official PSD scope relevant to their monitoring task.

Example output shape

{
  "signalType": "FORECAST_REVISION",
  "commodityCode": "0440000",
  "commodityName": "Example commodity",
  "countryCode": "BR",
  "countryName": "Example country",
  "marketYear": 2026,
  "changes": [
    {
      "rowKey": "0440000|BR|2026|28",
      "attributeId": 28,
      "attributeName": "Example attribute",
      "unitId": 8,
      "unitDescription": "Example unit",
      "before": 130000,
      "after": 132000,
      "delta": 2000,
      "direction": "RAISED"
    }
  ],
  "changedAttributeCount": 1
}

The values in this documentation example are illustrative and are not represented as current USDA observations.

Deterministic safe sample

mode: "sample" runs a self-contained synthetic demonstration through the production normalization, diff, bundling, signal-identity, and pending-queue logic.

It demonstrates:

1. one Corn/Brazil-like synthetic bundle with two changed attributes in one Dataset item;
2. a second synthetic commodity/country/year bundle with an upward revision;
3. a third synthetic bundle with a downward revision.

Hard sample guarantees:

• USDA HTTP requests: 0
• production named KVS open/read/write: 0
• production snapshot updated: false
• signal type: FORECAST_REVISION only
• synthetic values are not USDA observations

Update cadence

USDA PSD update frequency varies by commodity. USDA describes monthly review/update for WASDE-covered commodities, while some horticultural products are typically updated less frequently (for example, around twice per year).

The Actor is therefore positioned as a commodity-specific revision monitor, not as a claim that every PSD commodity is revised monthly. Schedule it according to the commodity scope and operational need.

Legal reuse and attribution

Dataset-specific evidence in the USDA Ag Data Commons record for the Foreign Agricultural Service Production, Supply and Distribution Database identifies FAS as publisher, Public Access Level as Public, and the licence as U.S. Public Domain. A separate USDA catalog-derived record may state CC BY 4.0; both permit commercial reuse.

This Actor uses the more conservative attribution posture:

Source: USDA Foreign Agricultural Service, Production, Supply and Distribution (PSD) Database.

No USDA endorsement is implied. USDA seals or logos are not used to imply endorsement.

Privacy

V1 processes commodity, country, market-year, attribute, unit, and numeric forecast data. It does not enrich or monitor personal data.

Important limitations

This Actor:

• detects snapshot-to-snapshot changes observed after baseline;
• does not reconstruct historical release vintages;
• does not predict commodity prices;
• does not provide trading or financial advice;
• does not claim every numeric revision is economically material;
• does not claim every commodity updates monthly.