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/tests/test_company_context.py

@@ -83,6 +83,23 @@ def test_optante_inconsistency_is_a_warning_not_a_guess():
     assert r["status"] == "PASS" and any("OPTANTE_SIMPLES" in w for w in r["warnings"])
 
 
+def test_contribuinte_ipi_is_auto_discovered_from_the_same_selected_c000004_row():
+    """C000004.CONTRIBUINTE_IPI (real column, same row already proven to be THE company by CRT/UF resolution) closes the fiscal-completion gap
+    where CST_IPI could not be resolved without asking an operator for a fact the ERP already proves."""
+    row = co("000001", CN_A)
+    row["contribuinte_ipi"] = "N"
+    r = resolve(ev([row], [emis()], DOC_A))
+    assert r["company_contribuinte_ipi"] == "N" and r["source_of_truth"]["contribuinte_ipi"] == "C000004"
+
+
+def test_contribuinte_ipi_absent_or_invalid_stays_unresolved_never_guessed():
+    r = resolve(ev([co("000001", CN_A)], [emis()], DOC_A))         # co() never sets contribuinte_ipi
+    assert r["company_contribuinte_ipi"] is None
+    row = co("000002", CN_B); row["contribuinte_ipi"] = "X"        # garbage value: never trusted
+    r2 = resolve(ev([row], [emis(cnpj=CN_B)], [{"cuf": "29", "cnpj": CN_B, "n": 1}]))
+    assert r2["company_contribuinte_ipi"] is None
+
+
 def test_full_cnpj_is_never_exposed():
     r = resolve(ev([co("1", CN_A)], [emis()], DOC_A))
     dump = str(preflight_report(r)) + str(r)

agent/tests/test_enrichment.py

@@ -70,7 +70,8 @@ DECISIONS = {"CLASSIFICACAO_FISCAL": {"status": "AUTO_FILL_SAFE", "value": "2202
 @pytest.fixture()
 def env(tmp_path):
     db = sqlite3.connect(":memory:", check_same_thread=False)
-    db.execute("CREATE TABLE C000025(CODIGO TEXT PRIMARY KEY, PRODUTO TEXT, GTIN TEXT, CLASSIFICACAO_FISCAL TEXT, CEST TEXT, IPI REAL, OTHER TEXT, CODBARRA TEXT)")
+    db.execute("CREATE TABLE C000025(CODIGO TEXT PRIMARY KEY, PRODUTO TEXT, GTIN TEXT, CLASSIFICACAO_FISCAL TEXT, CEST TEXT, IPI REAL, OTHER TEXT, CODBARRA TEXT, "
+              + ", ".join(f"{f} TEXT" for f in E.FISCAL_COMPLETION_FIELDS + E.CLASSIFICATION_CONTEXT_FIELDS) + ")")
     db.executemany("INSERT INTO C000025(CODIGO,PRODUTO,GTIN,OTHER) VALUES(?,?,?,?)", [(f"H{i}", f"HIST {i}", "", "keep") for i in range(50)])
     db.commit()
     hub = Hub(dict(ENABLED), DECISIONS)
@@ -114,6 +115,30 @@ def test_new_product_is_enriched_only_in_empty_fields_then_second_run_zero_write
     assert db.total_changes == before and len(hub.resolve_calls) == 1  # nothing re-processed, 0 writes
 
 
+def test_current_report_includes_fiscal_completion_and_classification_columns(tmp_path):
+    """`current` sent to the Hub used to carry only CLASSIFICACAO_FISCAL/CEST/IPI. field_contract.resolve_product (now wired into
+    /v1/products/resolve) also needs the current CFOP/CST/CSOSN/... values and the classification columns infer_role reads (TIPO/
+    PROD_COZINHA/PRODUTO_SERVICO/CODGRUPO) - otherwise it can never see what's already filled or auto-discover product_role."""
+    db = sqlite3.connect(":memory:", check_same_thread=False)
+    db.execute("CREATE TABLE C000025(CODIGO TEXT PRIMARY KEY, PRODUTO TEXT, GTIN TEXT, CLASSIFICACAO_FISCAL TEXT, CEST TEXT, IPI REAL, OTHER TEXT, CODBARRA TEXT, "
+              + ", ".join(f"{f} TEXT" for f in E.FISCAL_COMPLETION_FIELDS + E.CLASSIFICATION_CONTEXT_FIELDS) + ")")
+    db.commit()
+    hub = Hub(dict(ENABLED), DECISIONS)
+    store = E.EnrichmentStore(tmp_path / "e.db")
+    now = [1000.0]
+    worker = E.EnrichmentWorker(hub=hub, store=store, read_conn=lambda: Conn(db), write_conn=lambda: Conn(db), create_reprocess=lambda c: None, clock=lambda: now[0], sleep=lambda s: None)
+    worker.step()      # baseline
+    db.execute("INSERT INTO C000025(CODIGO,PRODUTO,GTIN,OTHER,CSOSN,TIPO,PRODUTO_SERVICO) VALUES(?,?,?,?,?,?,?)", ("N9", "PRODUTO X", "7891000100103", "keep", "102", "VENDA", None))
+    db.commit()
+    now[0] += 5
+    worker.step()
+    sent = hub.resolve_calls[0]["current"]
+    assert sent["CSOSN"] == "102" and sent["TIPO"] == "VENDA"
+    for f in E.FISCAL_COMPLETION_FIELDS + E.CLASSIFICATION_CONTEXT_FIELDS:
+        assert f in sent, f
+    assert hub.resolve_calls[0]["ev"] == {"recipes": [], "composed": [], "purchases": {}, "stock_entry": {}, "stock_in": {}}   # targeted evidence rides along (empty here: sqlite has no RDB$RELATION_FIELDS)
+
+
 def test_existing_value_is_never_overwritten(env):
     db, hub, store, worker, now, _ = env
     worker.step()

agent/tests/test_firebird_reader_product_evidence.py

@@ -0,0 +1,85 @@
+"""read_product_evidence: targeted, single-product evidence for the ad-hoc /v1/products/resolve call - the same recipes/composed/purchases/
+stock facts read_evidence already gathers for a full sync job, scoped to ONE product_code, never a full-table scan. Measured against a real
+production-equivalent database (D:\\PROJETOS\\GTISISTEMAS\\Banco\\GTI.FDB, read-only): a full read_evidence() scan took ~40ms for the whole
+catalog, and a targeted per-product lookup correctly drove field_contract.infer_role to RESALE/OWN_PRODUCTION for 5 of 8 real products with
+zero operator questions - this test locks in the behavior with a portable (sqlite) fixture."""
+import sqlite3
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parents[1] / "src"))
+from gti_fiscal_agent.firebird_reader import read_product_evidence
+
+
+def _conn():
+    db = sqlite3.connect(":memory:")
+    db.execute("CREATE TABLE RECEITA_INGREDIENTES(CODRECEITA TEXT)")
+    db.execute("CREATE TABLE C000032(CODPRODUTO TEXT, TIPO TEXT)")
+    db.execute("CREATE TABLE C000088(CODPRODUTO TEXT, ICMS_RETIDO TEXT, ICMS_VALORRETIDO REAL, SUB_VALOR REAL)")
+    db.execute("CREATE TABLE C000100(CODPRODUTO TEXT, ULTIMA_ENTRADA TEXT, NOTA_FISCAL TEXT, ENTRADAS REAL)")
+    return db
+
+
+def test_no_firebird_system_table_degrades_to_no_evidence_never_raises():
+    """A non-Firebird connection (this project's own sqlite test fakes) has no RDB$RELATION_FIELDS: the capability probe must degrade
+    gracefully to "no evidence", exactly like a missing table would, never raise."""
+    db = sqlite3.connect(":memory:")
+    ev = read_product_evidence(db, "000001")
+    assert ev == {"recipes": set(), "composed": set(), "purchases": {}, "stock_entry": {}, "stock_in": {}}
+
+
+def test_targeted_lookup_is_scoped_to_the_one_product_code():
+    db = _conn()
+    db.executemany("INSERT INTO RECEITA_INGREDIENTES VALUES (?)", [("000009",), ("000010",)])
+    db.execute("INSERT INTO C000032 VALUES ('000011', 'COMPOSICAO')")
+    db.execute("INSERT INTO C000088 VALUES ('000012', 'S', 0, 0)")
+    db.execute("INSERT INTO C000100 VALUES ('000013', '2026-01-01', '000001', 5)")
+    db.commit()
+
+    def has_relation_fields():
+        cur = db.cursor()
+        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')")
+        return cur.fetchall()
+
+    # sqlite has no RDB$RELATION_FIELDS either; monkeypatch the cursor to answer the capability probe like a real Firebird database would
+    class ProbedConn:
+        def __init__(self, real):
+            self.real = real
+
+        def cursor(self):
+            return ProbedCursor(self.real.cursor())
+
+    class ProbedCursor:
+        def __init__(self, real):
+            self.real = real
+            self._probe_result = None
+
+        def execute(self, sql, params=()):
+            if "RDB$RELATION_FIELDS" in sql:
+                self._probe_result = [
+                    ("RECEITA_INGREDIENTES", "CODRECEITA"), ("C000032", "CODPRODUTO"), ("C000032", "TIPO"),
+                    ("C000088", "CODPRODUTO"), ("C000088", "ICMS_RETIDO"), ("C000088", "ICMS_VALORRETIDO"), ("C000088", "SUB_VALOR"),
+                    ("C000100", "CODPRODUTO"), ("C000100", "ULTIMA_ENTRADA"), ("C000100", "NOTA_FISCAL"), ("C000100", "ENTRADAS"),
+                ]
+                return
+            self._probe_result = None
+            sqlite_sql = sql.replace("SELECT FIRST 1 ", "SELECT ") + (" LIMIT 1" if "FIRST 1" in sql else "")
+            self.real.execute(sqlite_sql, params)
+
+        def fetchall(self):
+            return self._probe_result if self._probe_result is not None else self.real.fetchall()
+
+        def fetchone(self):
+            return self.real.fetchone()
+
+    conn = ProbedConn(db)
+    ev = read_product_evidence(conn, "000009")
+    assert ev["recipes"] == {"000009"} and ev["composed"] == set() and ev["purchases"] == {} and ev["stock_entry"] == {} and ev["stock_in"] == {}
+    ev = read_product_evidence(conn, "000011")
+    assert ev["composed"] == {"000011"} and ev["recipes"] == set()
+    ev = read_product_evidence(conn, "000012")
+    assert ev["purchases"] == {"000012": [{"icms_retido": "S", "valor_retido": 0, "sub_valor": 0}]}
+    ev = read_product_evidence(conn, "000013")
+    assert ev["stock_entry"] == {"000013": True} and ev["stock_in"] == {"000013": True}
+    ev = read_product_evidence(conn, "999999")
+    assert ev == {"recipes": set(), "composed": set(), "purchases": {}, "stock_entry": {}, "stock_in": {}}

agent/tests/test_run_agent_service.py

@@ -346,6 +346,64 @@ def test_run_sends_heartbeat_but_never_polls_when_paused_centrally(monkeypatch,
     assert service.AgentState(config.state_db).stored_installation_id() == installation_id
 
 
+def test_company_context_for_heartbeat_resolves_once_and_caches(monkeypatch):
+    """CRT was never sent at heartbeat: the Agent already proves it (company_context.resolve, via preflight_company_context) for coverage/RTC
+    jobs, but that value never reached the Hub. This locks in the fix: resolved once, cached, never re-queried once solid."""
+    calls = {"n": 0}
+
+    def fake_preflight(env):
+        calls["n"] += 1
+        return {"status": "PASS", "company_uf": "BA", "company_crt": "1", "company_code": "000001"}
+
+    monkeypatch.setattr("gti_fiscal_agent.company_context.preflight_company_context", fake_preflight)
+    result, reason = service._company_context_for_heartbeat({}, None)
+    assert result == {"status": "PASS", "company_uf": "BA", "company_crt": "1", "company_code": "000001"} and reason is None and calls["n"] == 1
+    result2, reason2 = service._company_context_for_heartbeat({}, result)      # already cached: never re-queries Firebird
+    assert result2 is result and reason2 is None and calls["n"] == 1
+
+
+def test_company_context_for_heartbeat_retries_while_unresolved_never_guesses(monkeypatch):
+    def fake_preflight(env):
+        return {"status": "FAIL", "classification": "UNRESOLVED", "reasons": ["UF_SOURCE_UNKNOWN"]}
+
+    monkeypatch.setattr("gti_fiscal_agent.company_context.preflight_company_context", fake_preflight)
+    result, reason = service._company_context_for_heartbeat({}, None)
+    assert result is None and "UNRESOLVED" in reason        # never a guessed uf/crt - explicitly unresolved, retried next tick
+
+
+def test_run_heartbeat_carries_the_auto_discovered_company_crt(monkeypatch, tmp_path):
+    """End-to-end: once company context resolves, the CRT rides the heartbeat payload the Hub already knows how to store
+    (Installation.company_crt) - closing the transport gap without any Hub change."""
+    stopper = _ExternalStopFlag()
+    fake_hub = _FakeHubForLoop()
+    installation_id = "00000000-0000-4000-8000-000000000333"
+    sent = {}
+
+    def identity():
+        return {"agent_id": 2, "installation_id": installation_id}
+
+    def heartbeat_metadata(payload):
+        sent.update(payload)
+        stopper.stop = True
+        return {"agent_id": 2, "processing_enabled": False}
+
+    fake_hub.identity = identity
+    fake_hub.heartbeat_metadata = heartbeat_metadata
+    fake_hub.next_job = lambda: (_ for _ in ()).throw(AssertionError("paused centrally; next_job must not be called"))
+    monkeypatch.setattr(service, "HubClient", lambda *a, **k: fake_hub)
+    monkeypatch.setattr(service, "load_executor", lambda: _FakeExecutor())
+    monkeypatch.setattr(service.time, "sleep", lambda _seconds: None)
+    monkeypatch.setattr("gti_fiscal_agent.company_context.preflight_company_context",
+                        lambda env: {"status": "PASS", "company_uf": "BA", "company_crt": "1", "company_code": "000001", "company_contribuinte_ipi": "N"})
+
+    config = _config(agent_id="2", poll_interval_seconds=0, state_db=str(tmp_path / "agent.db"))
+    env = {"AGENT_ID": "2", "FIREBIRD_DATABASE_PATH": AUTHORIZED, "FIREBIRD_WRITES": "0", "FISCAL_MODE": "DRY_RUN"}
+
+    service.run(config, env, stopper=stopper)
+
+    assert sent["company_uf"] == "BA" and sent["company_crt"] == "1" and sent["company_contribuinte_ipi"] == "N"
+
+
 def test_run_honors_an_externally_supplied_stopper(monkeypatch):
     # This is exactly the pattern the Windows Service wrapper uses: it never
     # constructs GracefulStop() (which would crash off the main thread), it