GTI_GERENCIADOR_FISCAL/docs/MULTI_DATABASE_FINDINGS_V1.md

# MULTI_DATABASE_FINDINGS_V1

Read-only audit of the copies in `Banco/` (no Firebird writes, no new fiscal rules, no new datasets). Segment = inferred from table population and the company name stored in C000004, never from the file name.

## Databases

| file | segment (evidence) | products | company UF/CRT (C000004) | EMISSOR.EMITENTE_CRT | schema class |
|---|---|---|---|---|---|
| CONSTRUCAO.FDB | CONSTRUCTION | 3712 | BA/1 | ['1'] | COMPATIBLE_WITH_VARIATIONS |
| MMMODAS.FDB | APPAREL | 20997 | BA/2 | ['1'] | COMPATIBLE_WITH_VARIATIONS |
| RINCAO.FDB | RESTAURANT | 894 | UNAVAILABLE (3 company rows) | ['3'] | COMPATIBLE_WITH_VARIATIONS |
| UNIAO.FDB | RETAIL_MARKET | 8942 | BA/3 | ['1'] | COMPATIBLE_WITH_VARIATIONS |

Company-context findings: C000004.CRT disagrees with EMISSOR.EMITENTE_CRT in 3 of the 4 copies, OPTANTE_SIMPLES=S coexists with CRT=3 (UNIAO) and OPTANTE_SIMPLES=N with CRT=2 (MMMODAS); RINCAO's C000004 holds 3 company rows (fail-closed: context ambiguous). The Agent must not guess: it needs an explicit company selection and a decided CRT source of truth.

## Fiscal coverage (Fiscal Engine V1, read-only)

| metric | CONSTRUCAO.FDB | MMMODAS.FDB | RINCAO.FDB | UNIAO.FDB |
|---|---|---|---|---|
| TOTAL_PRODUCTS | 3712 | 20997 | 894 | 8942 |
| NCM_VALID | 3698 | 20881 | 894 | 8851 |
| NCM_LEGACY | 0 | 0 | 0 | 3 |
| NCM_INVALID | 14 | 116 | 0 | 88 |
| NCM_MISSING | 0 | 0 | 0 | 0 |
| IPI_NUMERIC | 1497 | 1947 | 349 | 2469 |
| IPI_NON_NUMERIC | 63 | 38 | 18 | 249 |
| IPI_SOURCE_BLANK | 1220 | 18887 | 378 | 3150 |
| IPI_AMBIGUOUS | 918 | 9 | 149 | 2983 |
| IPI_NO_MATCH | 14 | 116 | 0 | 88 |
| IPI_ALREADY_CORRECT | 0 | 0 | 0 | 0 |
| IPI_CHANGE_REQUIRED | 1497 | 1947 | 349 | 2469 |
| IPI_WRITE_ELIGIBLE | 1497 | 1947 | 349 | 2469 |
| CEST_CONFIRMED | 0 | 0 | 0 | 4 |
| CEST_CANDIDATES | 0 | 45 | 2 | 42 |
| CFOP_RESOLVED | 2198 | 20798 | 0 | 5944 |
| CFOP_CONTEXT_REQUIRED | 1514 | 199 | 894 | 2998 |
| CSOSN_RESOLVED | 0 | 0 | 0 | 0 |
| CSOSN_CANDIDATES | 74 | 0 | 0 | 0 |
| CSOSN_CONTEXT_REQUIRED | 3638 | 20997 | 894 | 8942 |
| ST_CONFIRMED | 867 | 0 | 0 | 297 |
| ST_CANDIDATE | 434 | 26 | 0 | 1706 |
| ST_UNKNOWN | 2337 | 20933 | 894 | 6444 |
| ST_NOT_APPLICABLE | 74 | 38 | 0 | 495 |
| PRODUCT_ROLE_KNOWN | 3708 | 20909 | 668 | 8922 |
| PRODUCT_ROLE_UNKNOWN | 4 | 88 | 226 | 20 |
| ST_WITHHOLDING_CONFIRMED | 0 | 0 | 0 | 0 |
| ST_WITHHOLDING_NOT_CONFIRMED | 0 | 10039 | 0 | 0 |
| ST_WITHHOLDING_UNKNOWN | 3712 | 10958 | 894 | 8942 |

Guards: ST/MVA dataset is BA-only and CSOSN logic needs CRT=1; when the company context does not satisfy them the engine reports context-required instead of applying a rule (`guards_applied` in the coverage artifact).

## Segment comparison

| indicator | CONSTRUCAO.FDB (CONSTRUCTION) | MMMODAS.FDB (APPAREL) | RINCAO.FDB (RESTAURANT) | UNIAO.FDB (RETAIL_MARKET) |
|---|---|---|---|---|
| NCM valid share | 99.6% | 99.4% | 100.0% | 99.0% |
| CEST filled | 93.4% | 0.0% | 71.6% | 86.2% |
| CSOSN filled | 99.9% | 99.7% | 99.0% | 100.0% |
| CFOP distinct values | 3 | 5 | 4 | 5 |
| CFOP top | [['5405', 2266], ['5102', 1444], [None, 2]] | [['5102', 20935], [None, 54], ['5101', 6]] | [['5102', 666], ['5405', 226], ['1556', 1]] | [['5102', 6837], ['5405', 2102], [None, 1]] |
| SITUACAO_TRIBUTARIA | {'T': 3687, 'null': 25} | {'T': 20994, 'null': 3} | {'T': 893, 'null': 1} | {'T': 8914, 'null': 28} |
| ST_CANDIDATE+CONFIRMED (BA dataset) | 1301 | 26 | 0 | 2003 |
| purchase items C000088 | 0 | 117657 | 0 | 0 |
| products with purchase evidence | 0 | 10041 | 0 | 0 |
| recipes / composed | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 |
| role known share | 99.9% | 99.6% | 74.7% | 99.8% |
| IPI numeric share | 40.3% | 9.3% | 39.0% | 27.6% |
| IPI already stored | 0.0% | 0.0% | 0.0% | 0.0% |

## Where the gaps come from

- **ERP-wide (0 in every database):** CSOSN_RESOLVED, ST_WITHHOLDING_CONFIRMED. These are limits of the SGV data model / current rules, not of one client.
- **Client/segment:** CEST filling varies from near-empty (apparel) to mostly filled (market/restaurant/construction) — segment-shaped (goods under ST agreements), but each segment has ONE database here, so client vs segment cannot be separated.
- **Company context (client-specific and ERP-wide):** CRT/regime data is inconsistent inside the same ERP (C000004 vs EMISSOR vs OPTANTE_SIMPLES); it is a data-quality/config issue every client needs to settle.
- **No auto-repair (oficina) database was provided** (`Banco/` holds construction, apparel, restaurant and market copies); auto-repair conclusions are NOT drawn.

## GUI map validation (21 write targets + origin)

All 21 write-target columns exist in all databases (21 present everywhere); the only type variation is {"CEST": {"UNIAO.FDB": {"reference": [37, 7, 0], "this": [37, 10, 0]}}}. Value patterns repeat across databases (CST 3-digit origin+CST, CSOSN 102/500/101, SITUACAO_TRIBUTARIA T, IAT/IPPT/INCIDENCIA constants, PIS/COFINS columns almost empty), which supports the DFM-derived map without changing it.

Origin (`COD_ORIGEM_MERCADORIA`): populated counts per database {"CONSTRUCAO.FDB": 1, "MMMODAS.FDB": 0, "RINCAO.FDB": 0, "UNIAO.FDB": 6}; observed values {"CONSTRUCAO.FDB": [[null, 3711], ["2", 1]], "MMMODAS.FDB": [[null, 20997]], "RINCAO.FDB": [[null, 894]], "UNIAO.FDB": [[null, 8936], ["1", 3], ["0", 2], ["2", 1]]}. Values stay inside the 0/1/2 domain, but so few rows are populated that this is weak correlation: the field stays **PROBABLE** until a UI diff on the radio group.

## Architecture answer

**CAN_USE_ONE_GENERIC_AGENT=true.** All four databases expose C000004 and C000025 with every write-target column; differences are optional tables, one column length (CEST VARCHAR(10) vs (7)) and company-context quality. Required capabilities: `supports_ncm`, `supports_ipi` (only IPI is written today), `supports_cest`, C000025+C000004 present, an unambiguous (or explicitly configured) company context, and the write executor's live column-length/type check. Detected-but-optional: `supports_csosn/cfop/cst/pis/cofins/origin/iat/incidence/ippt`, and evidence tables (C000088, C000100, RECEITA_INGREDIENTES, NFCE_ITENS) which only enrich validation. No per-client Agent is needed; per-client configuration is: company selector (C000004.CODIGO), CRT source of truth, and the authorized write path/fingerprint (pilot two-layer authorization).


## Additional observations

- **IPI_WRITE_ELIGIBLE is engine eligibility, not permission.** Real-client copies store IPI in at most 1 product (none had it filled), so every numeric TIPI match shows as a change (CONSTRUCAO 1497, MMMODAS 1947, RINCAO 349, UNIAO 2469). Policy stays: real-client databases are read-only unless the two-layer pilot authorization (path + schema fingerprint) is configured per installation.
- **Regime guards mattered:** MMMODAS (CRT=2) and UNIAO (CRT=3) are outside the CRT=1 assumption of the CSOSN engine, and RINCAO's company context is ambiguous, so their CSOSN/ST results are context-required by design, not by data quality.
- **ST evidence:** CONSTRUCAO has the most CEST-corroborated ST (867 ST_CONFIRMED: ERP CEST equals the BA Anexo 1 item CEST); withholding is still unproven everywhere (0 confirmed; MMMODAS has purchase items flagged ICMS_RETIDO='N'). CEST_LISTED_BUT_BA_ANNEX1_ABSENT keeps apparel in ST_UNKNOWN because the CONFAZ list also names apparel/footwear NCMs.
- **Method:** classification ran the production Classifier inside the hub container against PostgreSQL (read-only, memoized dataset lookups); 60 products compared with `/v1/classify/batch` gave 0 differences. Side finding: the Hub computes the decision before checking `classification_cache`, so the cache saves storage, not latency (~0.4 s/product over HTTP).
- **Not provided:** an auto-repair (oficina) database. Restaurant = RINCAO, market = UNIAO; CONSTRUCAO (construction materials) and MMMODAS (apparel) were extra segments.