feat: wire field_contract into product enrichment; auto-discover CRT/CONTRIBUINTE_IPI at heartbeat; targeted per-product ERP evidence

field_contract.resolve_product was only exercised by its own unit tests. /v1/products/resolve now calls it for every product whose NCM
resolves, merging CFOP/CST/CSOSN/PIS-COFINS/CST_IPI/SITUACAO_TRIBUTARIA/IAT/IPPT decisions alongside CLASSIFICACAO_FISCAL/CEST/IPI - reusing
the same engine, the same FiscalContextEntry table the blocker-resolution workflow already writes to, no duplicated rules.

Closes three real transport/discovery gaps found while wiring it in:
- Agent heartbeat never sent company_crt (env-var UF only) or company_contribuinte_ipi, so Installation.company_crt stayed permanently empty
  even though company_context.resolve() already proves both from C000004/EMISSOR for every coverage job. Resolved once, cached, retried only
  while unresolved. Migration 0032 adds Installation.company_contribuinte_ipi (NULL=unknown, never coerced to "N").
- The Agent's enrichment payload only ever reported 3 old fields (CLASSIFICACAO_FISCAL/CEST/IPI) as "current", so the Hub could never see the
  product's own CFOP/CST/CSOSN/... nor the classification columns (TIPO/PROD_COZINHA/PRODUTO_SERVICO/CODGRUPO) infer_role needs - separated
  into a read-only CURRENT_REPORT_FIELDS list, the write allowlist (PRODUCT_ENRICHMENT_WRITE_V1) untouched.
- Added a targeted, product_code-scoped evidence query (firebird_reader.read_product_evidence: recipes/composed/purchases/stock, indexed WHERE,
  never a full-table scan) so st_withheld/product_role can be proven for a single ad-hoc resolve, not only during a full sync job.

Verified read-only against the real database (D:\PROJETOS\GTISISTEMAS\Banco\GTI.FDB): CRT=1, CONTRIBUINTE_IPI=N, company_context.resolve()
reaches HIGH confidence; infer_role correctly resolved RESALE/OWN_PRODUCTION for 5/8 sample real products with zero operator questions.

1121 tests passed (tests + central/tests + agent/tests), 0 failed. Version 1.3.7 (single GTI_FISCAL_VERSION shared by Hub and Agent per
central/app/version.py's own design - never independently versioned).

agent/src/gti_fiscal_agent/company_context.py

@@ -59,7 +59,7 @@ def resolve(evidence, config=None):
     "nfce_keys": [{"cuf", "cnpj", "n"}], "nf_by_filial": {code: n}}. Pure function."""
     cfg = config or {}
     out = {"status": "FAIL", "classification": "UNRESOLVED", "company_code": None, "company_cnpj": None, "company_cnpj_fingerprint": None, "company_uf": None, "company_crt": None,
-           "source_of_truth": {}, "confidence": "NONE", "evidence": [], "warnings": [], "reasons": [], "configured": False}
+           "company_contribuinte_ipi": None, "source_of_truth": {}, "confidence": "NONE", "evidence": [], "warnings": [], "reasons": [], "configured": False}
 
     def fail(cls, reason):
         out["classification"] = cls; out["reasons"].append(reason); return out
@@ -93,6 +93,10 @@ def resolve(evidence, config=None):
     out["evidence"].append(f"company selected by {basis}")
     out.update(company_code=selected["code"], company_cnpj=mask_cnpj(selected["cnpj"]), company_cnpj_fingerprint=cnpj_fingerprint(selected["cnpj"]))
     out["source_of_truth"]["company"] = basis
+    contribuinte_ipi = _s(selected.get("contribuinte_ipi"))
+    if contribuinte_ipi and contribuinte_ipi.upper() in ("S", "N"):      # same row already proven to be THE company; no extra query, no extra trust needed
+        out["company_contribuinte_ipi"] = contribuinte_ipi.upper()
+        out["source_of_truth"]["contribuinte_ipi"] = "C000004"
 
     # ---- emitter (EMISSOR) must describe the same company --------------------------------------
     emissor = None
@@ -175,7 +179,7 @@ def collect_evidence(cursor):
         cols.setdefault(t, set()).add(f)
     ev = {"c000004": [], "emissor": [], "nfce_keys": [], "nf_by_filial": {}}
     c4 = cols.get("C000004", set())
-    want = [("CODIGO", "code"), ("CNPJ", "cnpj"), ("IE", "ie"), ("UF", "uf"), ("CRT", "crt"), ("OPTANTE_SIMPLES", "optante"), ("FILIAL", "name")]
+    want = [("CODIGO", "code"), ("CNPJ", "cnpj"), ("IE", "ie"), ("UF", "uf"), ("CRT", "crt"), ("OPTANTE_SIMPLES", "optante"), ("FILIAL", "name"), ("CONTRIBUINTE_IPI", "contribuinte_ipi")]
     use = [(c, k) for c, k in want if c in c4]
     if use:
         cursor.execute(f"SELECT {','.join(c for c, _ in use)} FROM C000004")
@@ -214,5 +218,5 @@ def preflight_company_context(env=None):
 
 
 def preflight_report(result):
-    keys = ("company_code", "company_cnpj", "company_uf", "company_crt", "source_of_truth", "confidence", "classification", "warnings", "reasons")
+    keys = ("company_code", "company_cnpj", "company_uf", "company_crt", "company_contribuinte_ipi", "source_of_truth", "confidence", "classification", "warnings", "reasons")
     return {"COMPANY_CONTEXT": "PASS" if result["status"] == "PASS" else "FAIL", **{k: result.get(k) for k in keys}}

agent/src/gti_fiscal_agent/enrichment.py

@@ -25,7 +25,17 @@ ALLOWED_FIELDS = ("CLASSIFICACAO_FISCAL", "CEST", "IPI")
 # TECHNICAL_PLACEHOLDER: the SGV refuses a product without NCM, so operators type a filler. It means "not classified yet" (not a human decision) and may be replaced.
 # Explicit per-field allowlist, identical to central/app/enrichment/placeholders.py (parity test). Nothing else is ever overwritten.
 PLACEHOLDERS = {"CLASSIFICACAO_FISCAL": frozenset({"00000000"})}            # explicit allowlist; anything else raises before touching SQL
-READ_FIELDS = ("CODIGO", "PRODUTO", "GTIN", "CODBARRA") + ALLOWED_FIELDS      # the SGV operator types the EAN in CODBARRA; GTIN (fiscal) is mostly empty
+# READ-ONLY reporting to the Hub for field_contract.resolve_product's post-NCM fiscal-completion decisions (CFOP/CST/CSOSN/PIS-COFINS/...).
+# This is NOT a write allowlist - PRODUCT_ENRICHMENT_WRITE_V1 still only ever writes ALLOWED_FIELDS above. Sending the CURRENT value of these
+# fields (and the classification columns below) just lets the Hub's field_contract engine see what's already filled and never guess.
+FISCAL_COMPLETION_FIELDS = ("SITUACAO_TRIBUTARIA", "CFOP", "CFOP_ENTRADA", "CST", "CST_ENTRADA", "CSOSN", "ALIQUOTA", "CST_IPI",
+                           "COD_ENTRADA_PIS", "COD_SAIDA_PIS", "ALIQ_PIS", "COD_ENTRADA_COFINS", "COD_SAIDA_COFINS", "ALIQ_COFINS",
+                           "INCIDENCIA_PISCOFINS", "PISCOFINS", "IAT", "IPPT")
+# Classification metadata field_contract.infer_role reads to auto-discover product_role (RESALE/OWN_PRODUCTION/INPUT/SERVICE) from real ERP
+# facts instead of asking the operator. Read-only here too.
+CLASSIFICATION_CONTEXT_FIELDS = ("CODGRUPO", "TIPO", "PROD_COZINHA", "PRODUTO_SERVICO")
+CURRENT_REPORT_FIELDS = ALLOWED_FIELDS + FISCAL_COMPLETION_FIELDS + CLASSIFICATION_CONTEXT_FIELDS
+READ_FIELDS = ("CODIGO", "PRODUTO", "GTIN", "CODBARRA") + CURRENT_REPORT_FIELDS      # the SGV operator types the EAN in CODBARRA; GTIN (fiscal) is mostly empty
 POLL_SECONDS = 2.0
 SAFETY_DIFF_SECONDS = 60.0
 OVERRIDE_CHECK_SECONDS = 20.0
@@ -327,9 +337,14 @@ class EnrichmentWorker:
         conn = self._open(self.read_conn)
         try:
             rows = read_rows(conn, [code])
+            row = rows.get(code)
+            if row is None or mode not in ("DRY_RUN", "ENABLED"):
+                ev = None
+            else:
+                from .firebird_reader import read_product_evidence      # targeted, indexed by product_code - never a full-table scan (see docstring)
+                ev = read_product_evidence(conn, code)
         finally:
             conn.close()
-        row = rows.get(code)
         if row is None:
             self.store.update(code, state="GONE")
             return
@@ -338,9 +353,10 @@ class EnrichmentWorker:
             self.store.update(code, state="SKIPPED_FEATURE", snapshot=snapshot)
             return
         attempts = int(item["attempts"] or 0) + 1
-        current = {f: row[f] for f in ALLOWED_FIELDS}
+        current = {f: row[f] for f in CURRENT_REPORT_FIELDS}
         try:
-            result = self.hub.resolve_product({"product_code": code, "gtin": pick_gtin(row), "description": _text(row["PRODUTO"]), "current": {k: (None if v is None else str(v)) for k, v in current.items()}})
+            result = self.hub.resolve_product({"product_code": code, "gtin": pick_gtin(row), "description": _text(row["PRODUTO"]), "ev": {k: (sorted(v) if isinstance(v, set) else v) for k, v in ev.items()},
+                                              "current": {k: (None if v is None else str(v)) for k, v in current.items()}})
         except Exception as error:  # noqa: BLE001 - Hub offline / slow: the product stays pending, the SGV is unaffected
             delay = RETRY_BACKOFF[min(attempts - 1, len(RETRY_BACKOFF) - 1)]
             self.store.update(code, state="RETRY", attempts=attempts, next_attempt_at=self.clock() + delay, last_state=f"HUB_ERROR:{type(error).__name__}")

agent/src/gti_fiscal_agent/firebird_reader.py

@@ -75,7 +75,56 @@ def read_company_context(env=None):
     result = preflight_company_context(env or os.environ)
     if result["status"] != "PASS":
         raise CompanyContextError(result)
-    return {"uf": result["company_uf"], "crt": result["company_crt"], "company_code": result["company_code"], "source_of_truth": result["source_of_truth"], "confidence": result["confidence"]}
+    return {"uf": result["company_uf"], "crt": result["company_crt"], "company_code": result["company_code"], "contribuinte_ipi": result.get("company_contribuinte_ipi"),
+           "source_of_truth": result["source_of_truth"], "confidence": result["confidence"]}
+
+
+def read_product_evidence(conn, code):
+    """Targeted, single-product evidence for an ad-hoc /v1/products/resolve call (new-product enrichment) - the same facts `read_evidence`
+    already gathers for a full sync job (recipes/composed/purchases/stock), but scoped to ONE product_code via an indexed WHERE, never a
+    full-table scan. Measured on a real production-equivalent database: read_evidence's full scan took ~40ms total for the whole catalog,
+    so this is not a correctness-driven optimization - it is what the mission explicitly asked for (never transport/scan the whole dataset
+    for one ad-hoc product). Every table/column is optional: a missing one just means less evidence (capability-based), matching
+    `read_evidence`. Takes an already-open connection (the SAME one the caller already opened for `read_rows`) - never opens its own,
+    so it works with the EnrichmentWorker's injected `read_conn` (including test fakes; a non-Firebird connection has no RDB$RELATION_FIELDS,
+    so the capability probe below degrades to "no evidence" rather than raising)."""
+    from collections import defaultdict
+    cur = conn.cursor()
+    cols = defaultdict(set)
+    try:
+        cur.execute("SELECT TRIM(RDB$RELATION_NAME), TRIM(RDB$FIELD_NAME) FROM RDB$RELATION_FIELDS WHERE RDB$RELATION_NAME IN ('C000032','C000088','C000100','RECEITA_INGREDIENTES')")
+        for t, f in cur.fetchall():
+            cols[t].add(f)
+    except Exception:
+        return {"recipes": set(), "composed": set(), "purchases": {}, "stock_entry": {}, "stock_in": {}}
+    has = lambda t, *c: t in cols and all(x in cols[t] for x in c)  # noqa: E731
+    s = lambda v: None if v is None else str(v).strip()  # noqa: E731
+    ev = {"recipes": set(), "composed": set(), "purchases": {}, "stock_entry": {}, "stock_in": {}}
+    code_padded = str(code).zfill(6)
+    if has("RECEITA_INGREDIENTES", "CODRECEITA"):
+        cur.execute("SELECT FIRST 1 CODRECEITA FROM RECEITA_INGREDIENTES WHERE CODRECEITA = ?", (code_padded,))
+        if cur.fetchone():
+            ev["recipes"] = {code_padded}
+    if has("C000032", "CODPRODUTO", "TIPO"):
+        cur.execute("SELECT FIRST 1 CODPRODUTO FROM C000032 WHERE CODPRODUTO = ? AND TIPO = 'COMPOSICAO'", (code,))
+        if cur.fetchone():
+            ev["composed"] = {s(code)}
+    if has("C000088", "CODPRODUTO", "ICMS_RETIDO", "ICMS_VALORRETIDO", "SUB_VALOR"):
+        cur.execute("SELECT ICMS_RETIDO, ICMS_VALORRETIDO, SUB_VALOR FROM C000088 WHERE CODPRODUTO = ?", (code,))
+        rows = [{"icms_retido": s(ret), "valor_retido": vr, "sub_valor": sv} for ret, vr, sv in cur.fetchall()]
+        if rows:
+            ev["purchases"][s(code)] = rows
+    if has("C000100", "CODPRODUTO", "ULTIMA_ENTRADA", "NOTA_FISCAL"):
+        cur.execute("SELECT FIRST 1 ULTIMA_ENTRADA, NOTA_FISCAL FROM C000100 WHERE CODPRODUTO = ?", (code,))
+        row = cur.fetchone()
+        if row:
+            ev["stock_entry"][s(code)] = row[0] is not None or s(row[1]) not in (None, "", "000000")
+    if has("C000100", "CODPRODUTO", "ENTRADAS"):
+        cur.execute("SELECT FIRST 1 ENTRADAS FROM C000100 WHERE CODPRODUTO = ?", (code,))
+        row = cur.fetchone()
+        if row:
+            ev["stock_in"][s(code)] = bool(row[0] and float(row[0]) > 0)
+    return ev
 
 
 def read_evidence(env=None, selected_company_code=None):

agent/src/gti_fiscal_agent/preflight.py

@@ -9,7 +9,7 @@ import os
 import sqlite3
 from pathlib import Path
 
-AGENT_VERSION_DEFAULT = "1.3.6"
+AGENT_VERSION_DEFAULT = "1.3.7"
 REQUIRED_ENV = ("GTI_HUB_URL", "AGENT_TOKEN", "FIREBIRD_DATABASE_PATH", "FB_USER", "FB_PASSWORD")
 REQUIRED_CAPABILITIES = ("supports_ncm", "supports_ipi", "supports_cest")
 FISCAL_MODES = ("DRY_RUN", "AUTO_APPLY")