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.

2 files changed, 36 insertions, 3 deletions

diff --git a/copy/cepis-status.cpy b/copy/cepis-status.cpy
index 75632c8..b98a753 100644
--- a/copy/cepis-status.cpy
+++ b/copy/cepis-status.cpy
@@ -1,7 +1,7 @@
 *> ---------------------------------------------------------------------
 *> Status layout without its 01 level, so the library can keep a private
 *> scratch status alongside the caller's without duplicating the
-*> definition. Replace the field-name tag and the level number.
+*> definition. Replace the field-name tag and the two level numbers.
 *>
 *> The six failure categories are split by the decision the caller has to
 *> make, not by the HTTP status that produced them.
@@ -21,3 +21,32 @@
 :L1:  :P:-STATUS-RETRY-AFTER-MS    PIC S9(9)
                                    SIGN IS LEADING SEPARATE.
 :L1:  :P:-STATUS-ATTEMPTS          PIC 9(4).
+
+*> The municipality a CEP that does not exist would have belonged to.
+*> Context for the error, never an address: the lookup is still
+*> :P:-NOT-FOUND and CEPIS-ADDRESS is still empty. Only GET /{cep} fills
+*> it, so it stays absent after a batch or a health call.
+*>
+*> :P:-FAIXA-CEP-INI and :P:-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. The range is sparse: Areal's 118 CEPs are
+*> scattered over the ~4900 numbers between 25845001 and 25849899, so the
+*> pair is a span to show a human, never a list of valid CEPs. That is
+*> what :P:-FAIXA-CEPS counts.
+*>
+*> The API omits "faixa" -- it never sends null -- when the CEP falls in
+*> a band no municipality owns, so test the flag before reading anything
+*> below it.
+:L1:  :P:-FAIXA.
+  :L2:  :P:-FAIXA-PRESENT          PIC X.
+        88  :P:-FAIXA-KNOWN        VALUE "Y".
+        88  :P:-FAIXA-ABSENT       VALUE "N".
+  :L2:  :P:-FAIXA-LOCALIDADE       PIC X(100).
+  :L2:  :P:-FAIXA-UF               PIC X(2).
+  :L2:  :P:-FAIXA-ESTADO           PIC X(60).
+  :L2:  :P:-FAIXA-REGIAO           PIC X(30).
+  :L2:  :P:-FAIXA-IBGE             PIC X(10).
+  :L2:  :P:-FAIXA-CEP-INI          PIC X(8).
+  :L2:  :P:-FAIXA-CEP-FIM          PIC X(8).
+  :L2:  :P:-FAIXA-CEPS             PIC 9(9).
diff --git a/copy/cepis.cpy b/copy/cepis.cpy
index 59d643c..84a9976 100644
--- a/copy/cepis.cpy
+++ b/copy/cepis.cpy
@@ -1,5 +1,5 @@
 *> ---------------------------------------------------------------------
-*> cepis 0.1.0 -- public data layouts for the cep.is client.
+*> cepis 0.2.0 -- public data layouts for the cep.is client.
 *>
 *> Copy this into WORKING-STORAGE (callers) or LINKAGE (subprograms).
 *> It defines, in order:
@@ -34,9 +34,13 @@
 *> categories are split by the decision the caller has to make, not by
 *> the HTTP status that produced them. CEPIS-RETRIABLE covers the three
 *> the client already retried on its own before giving up.
+*>
+*> A CEPIS-NOT-FOUND may also carry CEPIS-FAIXA, the municipality the
+*> missing CEP would have belonged to. CEPIS-FAIXA-PRESENT says whether
+*> it does; the call has still failed either way.
 01  CEPIS-STATUS.
     COPY "cepis-status.cpy" REPLACING
-        ==:P:== BY ==CEPIS== ==:L1:== BY ==05==.
+        ==:P:== BY ==CEPIS== ==:L1:== BY ==05== ==:L2:== BY ==10==.
 
 *> A CEP as the caller has it: "01001-000", "01001000" or "01001.000".
 01  CEPIS-CEP-INPUT                 PIC X(20).