> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrichment outcomes

> Parse explicit per-source success, absence, skip, ambiguity, and availability outcomes.

When an Evaluate engine enables an external enrichment source, its completed
output can include `output.enrichment.<kind>`. Under the v2 contract, every
configured and enabled source has a terminal block even when it has no payload.

## Block fields

| Field         | Type      | Required    | Meaning                                                                           |
| ------------- | --------- | ----------- | --------------------------------------------------------------------------------- |
| `kind`        | string    | yes         | Registered source identifier; matches the map key.                                |
| `status`      | enum      | yes         | `succeeded`, `not_mapped`, `skipped`, `ambiguous`, or `unavailable`.              |
| `attempted`   | boolean   | yes         | Whether this run made an upstream attempt. A cache hit or pre-call skip is false. |
| `payload`     | object    | conditional | Required for `succeeded` and `not_mapped`; absent otherwise.                      |
| `fetched_at`  | date-time | no          | Time of the upstream result. Cache hits retain the original time.                 |
| `diagnostics` | array     | no          | Source-scoped copy of matching top-level diagnostics.                             |

The canonical examples for all five statuses are in
[`assets/enrichment_outcomes_v2.json`](/assets/enrichment_outcomes_v2.json).
The machine-readable schema is `EnrichmentOutcomeBlock` in the OpenAPI file.

## Consumer logic

Branch on `status`, not block or payload presence:

* `succeeded`: consume the payload.
* `not_mapped`: record that the source returned no mapped feature, but do not
  interpret it as no risk. The FEMA summary is observational and does not feed
  deterministic rules.
* `skipped`: inspect diagnostics for missing input, address quality, or
  precision. `attempted` is false when no upstream call occurred.
* `ambiguous`: do not select a feature yourself. The source returned
  conflicting data and Nexio intentionally withheld a fact.
* `unavailable`: the quote result remains usable, but the enrichment signal is
  absent because of budget, transport, retry, breaker, schema, or internal
  serialization failure.

## Compatibility and non-guarantees

`ENRICHMENT_OUTCOME_V2` is a deployment-controlled rollout flag. With the flag
off, the legacy payload-only block remains and non-success blocks are absent.
Strict consumers must accept optional `payload` and `fetched_at` before v2 is
enabled for their traffic.

FEMA `flood_zone_confidence` is `address` in the legacy payload and `rooftop`
in v2. The legacy payload omits unknown `sfha` and
`base_flood_elevation_feet`; a successful v2 FEMA payload emits both as
explicit JSON `null` when unknown.

FEMA degraded and circuit-open diagnostics also use flag-conditional upstream
tokens. V2 emits `details.upstream` as `google_geocoding` or `nfhl`; the legacy
wire remains `geocoder` or `fema_nfhl` while the flag is off.

Public Google and FEMA data can be incomplete or stale and does not replace a
paid flood determination. `not_mapped` does not mean no flood risk. A cache hit
may replay a successful result fetched up to 24 hours earlier. The lookup has
an 8-second hard deadline; 5 seconds is the service objective, not a per-call
guarantee.