Expose the faixa a missing CEP would have belonged toHEADv0.2.0main

A CEP that fails is rarely a random number: it is someone who knows the
city and guessed the digits, and the classic guess is the -000 that 957
municipalities never received. The API now attaches that municipality to
the 404, and a caller left with nothing but "does not exist" cannot tell
a typo in a real city from a CEP that was never plausible.

It goes in CEPIS-STATUS, not CEPIS-ADDRESS. The call has still failed
and the address is still empty; putting a localidade where the address
lives would let a caller that forgets to test the status read Areal as
the answer to a CEP that does not exist.

Parsing is best effort throughout. faixa is omitted rather than sent as
null for a band no municipality owns, so its absence is the normal case
and there is a flag instead of a marker value; a block that is missing,
is not an object, or is short of localidade, uf, cep_ini, cep_fim and
ceps is dropped and the not-found comes back clean. Failing a 404 the
caller already understands over a decoration on it would be a poor
trade.

cep_ini and cep_fim are the CEPs that exist, not the bounds the Correios
publish, and the span between them is mostly empty -- hence ceps beside
them, so the pair is not read as a list.

1 files changed, 50 insertions, 2 deletions

diff --git a/README.md b/README.md
index 021448c..158112b 100644
--- a/README.md
+++ b/README.md
@@ -168,7 +168,7 @@ CALL "CEPIS-NORMALIZE-CEP" USING CEPIS-CEP-INPUT CEPIS-CEP CEPIS-STATUS
 | `CFG-BACKOFF-BASE-MS` | `500` | base of the exponential wait |
 | `CFG-BACKOFF-MAX-MS` | `8000` | cap on each wait, `Retry-After` included |
 | `CFG-TOTAL-TIMEOUT-MS` | `0` | cap on the whole call, attempts and waits included; `0` means none |
-| `CFG-USER-AGENT` | `cepis-cobol/0.1.0 (+https://cep.is)` | identifies the library and version |
+| `CFG-USER-AGENT` | `cepis-cobol/0.2.0 (+https://cep.is)` | identifies the library and version |
 
 Retries cover 429, 5xx and transport failures, with exponential backoff and
 full jitter; 400 and 404 are never retried.
@@ -189,7 +189,7 @@ already retried on its own before giving up.
 | condition | when | does retrying help? |
 | --- | --- | --- |
 | `CEPIS-INVALID-CEP` | not 8 digits | no |
-| `CEPIS-NOT-FOUND` | well-formed, not in the database | no |
+| `CEPIS-NOT-FOUND` | well-formed, not in the database; see `CEPIS-FAIXA` | no |
 | `CEPIS-RATE-LIMITED` | 429; see `CEPIS-STATUS-RETRY-AFTER-MS` | yes, later |
 | `CEPIS-SERVER-ERROR` | 5xx; see `CEPIS-STATUS-HTTP` | yes, later |
 | `CEPIS-NETWORK-ERROR` | DNS, connection, timeout, TLS | yes, later |
@@ -211,6 +211,54 @@ status seen and `CEPIS-STATUS-ATTEMPTS` how many attempts were made.
 API is answering instead of it — a captive Wi-Fi portal, a corporate proxy,
 an HTML error page. Useful as a diagnosis: the problem is not in your code.
 
+### Where a missing CEP would have been
+
+A `CEPIS-NOT-FOUND` from `CEPIS-LOOKUP` may also carry `CEPIS-FAIXA`: the
+municipality the CEP would have belonged to. A CEP that fails is rarely a
+random number — it is someone who knows the city and guessed the digits,
+and the classic guess is the `-000` that 957 municipalities never received.
+
+```cobol
+IF CEPIS-NOT-FOUND AND CEPIS-FAIXA-KNOWN
+    DISPLAY "no such CEP -- " FUNCTION TRIM (CEPIS-FAIXA-LOCALIDADE)
+            "/" CEPIS-FAIXA-UF " has " CEPIS-FAIXA-CEPS
+            " CEPs, from " CEPIS-FAIXA-CEP-INI
+            " to " CEPIS-FAIXA-CEP-FIM
+END-IF
+```
+
+**It is still a 404.** The lookup failed, `CEPIS-ADDRESS` is empty, and
+nothing in `CEPIS-FAIXA` is an address for the CEP that was asked for. It
+says where the guess landed, not what it resolves to.
+
+`CEPIS-FAIXA-CEP-INI` and `CEPIS-FAIXA-CEP-FIM` are the smallest and the
+largest CEP the municipality **actually has**, not the bounds the Correios
+publish. The DNE's own start for Areal/RJ is `25845000` — exactly the CEP
+that just failed, which is why the range comes back starting one past it,
+at `25845001`.
+
+**The span is sparse, and it is not a list.** Areal's 118 CEPs are
+scattered over the ~4900 numbers between `25845001` and `25849899`; almost
+none of that interval exists either. That is what `CEPIS-FAIXA-CEPS` is
+for — show it next to the pair, and never iterate the two as a range.
+
+The API omits `faixa` — it never sends it as null — when the CEP falls in a
+band no municipality owns, so **test `CEPIS-FAIXA-KNOWN` before reading
+anything below it.** A `faixa` that is missing, malformed, or short of its
+members leaves the flag off and the not-found otherwise untouched; a
+decoration on an error is never worth failing that error over.
+
+Only `CEPIS-LOOKUP` fills it. `CEPIS-LOOKUP-MANY` and `CEPIS-HEALTH` clear
+it, so `CEPIS-FAIXA-ABSENT` holds after a batch or a health call and a
+faixa never survives from one lookup into the next.
+
+| field | bytes | | field | bytes |
+| --- | --- | --- | --- | --- |
+| `faixa-localidade` | 100 | | `faixa-ibge` | 10 |
+| `faixa-uf` | 2 | | `faixa-cep-ini` | 8 |
+| `faixa-estado` | 60 | | `faixa-cep-fim` | 8 |
+| `faixa-regiao` | 30 | | `faixa-ceps` | `9(9)` |
+
 ## Field widths
 
 COBOL records are fixed width. A value longer than its field is truncated