chore: establish project baseline

agent/tests/conftest.py

@@ -0,0 +1,3 @@
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parents[1] / "src"))

agent/tests/test_company_context.py

@@ -0,0 +1,117 @@
+import pytest
+
+from gti_fiscal_agent.company_context import CompanyContextError, config_from_env, mask_cnpj, preflight_report, resolve
+from gti_fiscal_agent.firebird_reader import parse_company_context
+
+CN_A, CN_B, CN_C = "11111111000111", "22222222000122", "33333333000133"
+
+
+def co(code, cnpj, uf="BA", crt="1", optante="S"):
+    return {"code": code, "cnpj": cnpj, "uf": uf, "crt": crt, "optante": optante, "name": "X"}
+
+
+def ev(companies, emissor=None, docs=None):
+    return {"c000004": companies, "emissor": emissor if emissor is not None else [], "nfce_keys": docs or [], "nf_by_filial": {}}
+
+
+def emis(cnpj=CN_A, uf="BA", crt="1"):
+    return {"cnpj": cnpj, "uf": uf, "crt": crt}
+
+
+DOC_A = [{"cuf": "29", "cnpj": CN_A, "n": 100}]
+
+
+def test_single_company_all_sources_agree_is_auto_resolved():
+    r = resolve(ev([co("000001", CN_A)], [emis()], DOC_A))
+    assert r["status"] == "PASS" and r["classification"] == "AUTO_RESOLVED" and r["company_uf"] == "BA" and r["company_crt"] == "1" and r["confidence"] == "HIGH"
+    assert "DOCUMENT_KEYS" in r["source_of_truth"]["uf"]
+
+
+def test_multiple_rows_resolved_only_through_emitter_identity_never_first_row():
+    rows = [co("000001", CN_B, "SP", None, "N"), co("000005", CN_A), co("000007", CN_C, "BA", None, "N")]
+    r = resolve(ev(rows, [emis(CN_A)], DOC_A))
+    assert r["status"] == "PASS" and r["company_code"] == "000005" and r["source_of_truth"]["company"] == "EMISSOR_CNPJ_MATCH"
+
+
+def test_multiple_rows_without_disambiguation_requires_config():
+    rows = [co("000001", CN_A), co("000002", CN_B)]
+    r = resolve(ev(rows, []))
+    assert r["status"] == "FAIL" and r["classification"] == "CONFIG_REQUIRED" and r["company_code"] is None
+    assert resolve(ev(rows, [emis(CN_C)]))["classification"] == "CONFIG_REQUIRED"  # emitter matches none
+    ok = resolve(ev(rows, [], []), {"company_code": "000002"})
+    assert ok["status"] == "PASS" and ok["company_code"] == "000002" and ok["classification"] == "CONFIGURED"
+
+
+def test_configured_company_must_exist_and_agree_with_emitter():
+    rows = [co("000001", CN_A), co("000002", CN_B)]
+    assert resolve(ev(rows, [emis(CN_A)]), {"company_cnpj": "99999999999999"})["classification"] == "CONFIG_REQUIRED"
+    r = resolve(ev(rows, [emis(CN_A)], DOC_A), {"company_code": "000002"})
+    assert r["status"] == "FAIL" and r["classification"] == "CONFLICT"  # selected company differs from the emitter: unexplained
+
+
+def test_documents_only_from_another_cnpj_conflict_but_mixed_history_is_a_warning():
+    r = resolve(ev([co("000001", CN_A)], [emis()], [{"cuf": "29", "cnpj": CN_B, "n": 10}]))
+    assert r["status"] == "FAIL" and r["classification"] == "CONFLICT"
+    r = resolve(ev([co("000001", CN_A)], [emis()], [{"cuf": "29", "cnpj": CN_A, "n": 10}, {"cuf": "29", "cnpj": CN_B, "n": 1}]))
+    assert r["status"] == "PASS" and any("HISTORICAL_NFCE_KEYS_FROM_OTHER_CNPJ" in w for w in r["warnings"])
+
+
+def test_uf_conflict_and_unknown():
+    assert resolve(ev([co("1", CN_A, "BA")], [emis(uf="SP")]))["classification"] == "CONFLICT"
+    assert resolve(ev([co("1", CN_A, "BA")], [emis()], [{"cuf": "35", "cnpj": CN_A, "n": 5}]))["classification"] == "CONFLICT"  # key says SP
+    assert resolve(ev([co("1", CN_A, "")], [emis(uf="")]))["classification"] == "UNRESOLVED"
+
+
+def test_crt_conflict_needs_explicit_source_and_records_it():
+    base = ev([co("1", CN_A, crt="3")], [emis(crt="1")], DOC_A)
+    r = resolve(base)
+    assert r["status"] == "FAIL" and r["classification"] == "CONFLICT" and r["crt_candidates"] == {"EMISSOR": "1", "C000004": "3"}
+    ok = resolve(base, {"crt_source": "EMISSOR"})
+    assert ok["status"] == "PASS" and ok["company_crt"] == "1" and ok["classification"] == "CONFIGURED" and ok["confidence"] == "MEDIUM"
+    assert resolve(base, {"crt_source": "C000004"})["company_crt"] == "3"
+    assert resolve(base, {"crt_source_invalid": True})["classification"] == "CONFIG_REQUIRED"
+
+
+def test_crt_unknown_fails_and_single_source_is_flagged():
+    assert resolve(ev([co("1", CN_A, crt=None)], [emis(crt="")]))["classification"] == "UNRESOLVED"
+    r = resolve(ev([co("1", CN_A, crt=None)], [emis(crt="1")]))
+    assert r["status"] == "PASS" and "CRT_HAS_A_SINGLE_SOURCE" in r["warnings"]
+
+
+def test_optante_inconsistency_is_a_warning_not_a_guess():
+    r = resolve(ev([co("1", CN_A, crt="3", optante="S")], [emis(crt="3")]))
+    assert r["status"] == "PASS" and any("OPTANTE_SIMPLES" in w for w in r["warnings"])
+
+
+def test_full_cnpj_is_never_exposed():
+    r = resolve(ev([co("1", CN_A)], [emis()], DOC_A))
+    dump = str(preflight_report(r)) + str(r)
+    assert CN_A not in dump and mask_cnpj(CN_A) == "11**********11"
+
+
+def test_read_company_context_fails_closed(monkeypatch):
+    from gti_fiscal_agent import company_context as cc, firebird_reader as fr
+    monkeypatch.setattr(cc, "preflight_company_context", lambda env: resolve(ev([co("1", CN_A), co("2", CN_B)], [])))
+    with pytest.raises(CompanyContextError):
+        fr.read_company_context({})
+    monkeypatch.setattr(cc, "preflight_company_context", lambda env: resolve(ev([co("1", CN_A)], [emis()], DOC_A)))
+    assert fr.read_company_context({})["uf"] == "BA"
+
+
+def test_config_from_env_and_legacy_parser_unchanged():
+    assert config_from_env({"COMPANY_CODE": " 000005 ", "COMPANY_CNPJ": "11.111.111/0001-11", "COMPANY_CRT_SOURCE": "emissor"}) == {"company_code": "000005", "company_cnpj": "11111111000111", "crt_source": "EMISSOR", "crt_source_invalid": False, "uf_override": None}
+    assert config_from_env({"COMPANY_CRT_SOURCE": "x"})["crt_source_invalid"] is True
+    assert parse_company_context([("ba", "1")]) == {"uf": "BA", "crt": "1"}
+
+
+def test_auto_crt_source_and_uf_override_semantics():
+    assert config_from_env({"COMPANY_CRT_SOURCE": "AUTO"}) ["crt_source"] is None and config_from_env({"COMPANY_CRT_SOURCE": "AUTO"})["crt_source_invalid"] is False
+    conflict = ev([co("1", CN_A, crt="3")], [emis(crt="1")], DOC_A)
+    assert resolve(conflict, config_from_env({"COMPANY_CRT_SOURCE": "AUTO"}))["status"] == "FAIL"  # AUTO never hides a CRT conflict
+    good = ev([co("1", CN_A)], [emis()], DOC_A)
+    assert resolve(good, {"uf_override": "BA"})["status"] == "PASS"
+    r = resolve(good, {"uf_override": "SP"})
+    assert r["status"] == "FAIL" and r["classification"] == "CONFLICT"  # override never replaces the resolver silently
+    blank = ev([co("1", CN_A, uf="")], [emis(uf="")])
+    r = resolve(blank, {"uf_override": "BA"})
+    assert r["status"] == "PASS" and "UF_FROM_EXPLICIT_OVERRIDE" in r["warnings"]

agent/tests/test_ipi_auto_apply.py

@@ -0,0 +1,52 @@
+from gti_fiscal_agent.ipi_auto_apply import ipi_write_decision
+
+
+def _decision(ipi_status="IPI_RESOLVED", status="EXACT_NCM", ipi=None):
+    return {"status": status, "ipi_status": ipi_status, "classification": {"ipi": ipi}}
+
+
+def test_numeric_null_current_is_eligible():
+    d = ipi_write_decision(_decision(ipi={"rate_kind": "NUMERIC", "rate_numeric": 3.25}), None)
+    assert d["eligible"] is True
+    assert d["proposed_value"] == 3.25
+    assert d["reason_code"] == "CHANGE_REQUIRED"
+
+
+def test_numeric_same_value_is_not_eligible():
+    d = ipi_write_decision(_decision(ipi={"rate_kind": "NUMERIC", "rate_numeric": 3.25}), 3.25)
+    assert d["eligible"] is False
+    assert d["reason_code"] == "SAME_VALUE"
+
+
+def test_numeric_different_value_is_eligible():
+    d = ipi_write_decision(_decision(ipi={"rate_kind": "NUMERIC", "rate_numeric": 3.25}), 0)
+    assert d["eligible"] is True
+    assert d["proposed_value"] == 3.25
+
+
+def test_non_numeric_never_eligible():
+    d = ipi_write_decision(_decision(ipi={"rate_kind": "NON_NUMERIC", "rate_numeric": None}), None)
+    assert d["eligible"] is False
+    assert d["reason_code"] == "RATE_KIND_NON_NUMERIC"
+
+
+def test_source_blank_never_eligible():
+    d = ipi_write_decision(_decision(ipi={"rate_kind": "BLANK", "rate_numeric": None}), None)
+    assert d["eligible"] is False
+    assert d["reason_code"] == "RATE_KIND_BLANK"
+
+
+def test_ambiguous_ipi_status_never_eligible():
+    d = ipi_write_decision(_decision(ipi_status="IPI_CANDIDATES", ipi=None), None)
+    assert d["eligible"] is False
+
+
+def test_no_match_never_eligible():
+    d = ipi_write_decision(_decision(ipi_status="NO_TIPI_MAPPING_FOUND", ipi=None), None)
+    assert d["eligible"] is False
+
+
+def test_legacy_ncm_never_eligible():
+    d = ipi_write_decision(_decision(status="LEGACY_NCM", ipi_status="LEGACY_NCM"), None)
+    assert d["eligible"] is False
+    assert d["reason_code"] == "LEGACY_NCM"

agent/tests/test_preflight_and_dry_run.py

@@ -0,0 +1,132 @@
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+from gti_fiscal_agent.company_context import resolve
+from gti_fiscal_agent.preflight import major_minor, run_preflight
+
+ROOT = Path(__file__).parents[2]
+spec = importlib.util.spec_from_file_location("run_agent_service", ROOT / "agent" / "scripts" / "run_agent_service.py")
+service = importlib.util.module_from_spec(spec); sys.modules[spec.name] = service; spec.loader.exec_module(service)
+
+CN = "11111111000111"
+
+
+def env(tmp_path, **over):
+    base = {"GTI_HUB_URL": "http://hub.test", "AGENT_TOKEN": "SECRETTOKENVALUE9", "FIREBIRD_DATABASE_PATH": "x.fdb", "FB_USER": "u", "FB_PASSWORD": "SECRETPASSVALUE9", "FISCAL_MODE": "DRY_RUN", "FIREBIRD_WRITES": "0",
+            "AGENT_STATE_DB": str(tmp_path / "state.sqlite"), "AGENT_LOG_PATH": str(tmp_path / "logs" / "a.log"), "AGENT_VERSION": "1.0.0-rc1"}
+    base.update(over)
+    return base
+
+
+def http_ok(url, token=None, timeout=10):
+    if url.endswith("/health"):
+        return 200, {"status": "ok"}
+    if url.endswith("/version"):
+        return 200, {"version": "1.0.0-rc1"}
+    return (200 if token == "SECRETTOKENVALUE9" else 401), {}
+
+
+def fake_probe(company_over=None, caps_missing=()):
+    def probe(env):
+        cols = {"CLASSIFICACAO_FISCAL": (37, 20), "CFOP_ENTRADA": (14, 4), "CST_ENTRADA": (14, 4), "CFOP": (37, 4), "CST": (37, 10), "ALIQUOTA": (16, 8), "CEST": (37, 7), "SITUACAO_TRIBUTARIA": (37, 2),
+                "COD_ENTRADA_COFINS": (37, 3), "COD_SAIDA_COFINS": (37, 3), "ALIQ_COFINS": (37, 8), "COD_ENTRADA_PIS": (37, 3), "COD_SAIDA_PIS": (37, 3), "ALIQ_PIS": (37, 8), "CSOSN": (37, 60), "IPI": (27, 8),
+                "CST_IPI": (14, 3), "IAT": (37, 1), "INCIDENCIA_PISCOFINS": (37, 30), "PISCOFINS": (37, 1), "IPPT": (37, 1), "EX_TIPI": (37, 3), "COD_ORIGEM_MERCADORIA": (8, 4)}
+        for c in caps_missing:
+            cols.pop(c)
+        ev = {"c000004": [{"code": "000001", "cnpj": CN, "uf": "BA", "crt": "1", "optante": "S"}], "emissor": [{"cnpj": CN, "uf": "BA", "crt": "1"}], "nfce_keys": [{"cuf": "29", "cnpj": CN, "n": 5}], "nf_by_filial": {}}
+        ev.update(company_over or {})
+        return {"server_version": "WI-V6.3.9 Firebird 2.5", "ods": "11.2", "tables": {"C000004": {}, "C000025": cols}, "products": 3712, "company": resolve(ev, {})}
+    return probe
+
+
+def test_preflight_passes_for_a_clean_dry_run_installation(tmp_path):
+    r = run_preflight(env(tmp_path), http_get=http_ok, probe=fake_probe())
+    assert r["PREFLIGHT"] == "PASS" and r["blockers"] == [] and r["effective_firebird_writes"] is False
+    names = {c["name"] for c in r["checks"]}
+    assert {"HUB_REACHABLE", "AUTH", "HUB_VERSION_COMPATIBLE", "FIREBIRD_REACHABLE", "C000004", "C000025", "CAPABILITIES", "COMPANY_CONTEXT", "UF", "CRT", "SCHEMA_TYPE_GUARDS", "SQLITE", "LOG_DIRECTORY", "FISCAL_MODE", "FIREBIRD_WRITES"} <= names
+    assert "SECRETTOKENVALUE9" not in str(r) and "SECRETPASSVALUE9" not in str(r)
+
+
+@pytest.mark.parametrize("over,blocker", [
+    ({"FISCAL_MODE": "DRY_RUN", "FIREBIRD_WRITES": "1"}, "FIREBIRD_WRITES"),
+    ({"FISCAL_MODE": ""}, "FISCAL_MODE"),
+    ({"AGENT_TOKEN": ""}, "CONFIG"),
+])
+def test_preflight_blocks_bad_config(tmp_path, over, blocker):
+    r = run_preflight(env(tmp_path, **over), http_get=http_ok, probe=fake_probe())
+    assert r["PREFLIGHT"] == "FAIL" and any(b.startswith(blocker) for b in r["blockers"])
+
+
+def test_preflight_fails_on_hub_auth_version_and_missing_capability(tmp_path):
+    def bad_auth(url, token=None, timeout=10):
+        return http_ok(url, "wrong" if token else None)
+    assert any(b.startswith("AUTH") for b in run_preflight(env(tmp_path), http_get=bad_auth, probe=fake_probe())["blockers"])
+
+    def old_hub(url, token=None, timeout=10):
+        return (200, {"version": "0.9.0"}) if url.endswith("/version") else http_ok(url, token)
+    assert any(b.startswith("HUB_VERSION_COMPATIBLE") for b in run_preflight(env(tmp_path), http_get=old_hub, probe=fake_probe())["blockers"])
+    assert any(b.startswith("CAPABILITIES") for b in run_preflight(env(tmp_path), http_get=http_ok, probe=fake_probe(caps_missing=("CEST",)))["blockers"])
+
+
+def test_preflight_fails_when_company_context_is_ambiguous_or_crt_conflicts(tmp_path):
+    two = {"c000004": [{"code": "1", "cnpj": CN, "uf": "BA", "crt": "1"}, {"code": "2", "cnpj": "22222222000122", "uf": "SP", "crt": "1"}], "emissor": []}
+    r = run_preflight(env(tmp_path), http_get=http_ok, probe=fake_probe(two))
+    assert r["PREFLIGHT"] == "FAIL" and any(b.startswith("COMPANY_CONTEXT") for b in r["blockers"])
+    conflict = {"emissor": [{"cnpj": CN, "uf": "BA", "crt": "3"}]}
+    assert any("CRT_SOURCE_CONFLICT" in b for b in run_preflight(env(tmp_path), http_get=http_ok, probe=fake_probe(conflict))["blockers"])
+
+
+def test_hub_unreachable_is_a_clear_blocker(tmp_path):
+    def down(url, token=None, timeout=10):
+        raise ConnectionError("nope")
+    r = run_preflight(env(tmp_path), http_get=down, probe=fake_probe())
+    assert r["PREFLIGHT"] == "FAIL" and any(b.startswith("HUB_REACHABLE") for b in r["blockers"])
+
+
+def test_major_minor():
+    assert major_minor("1.0.0-rc1") == "1.0" and major_minor("1.0.3") == "1.0" and major_minor("0.9.0") != major_minor("1.0.0-rc1")
+
+
+# ---------------- zero-write guarantee ----------------
+def test_dry_run_makes_writes_technically_impossible_whatever_firebird_writes_says():
+    for extra in ({"FIREBIRD_WRITES": "1", "FISCAL_MODE": "DRY_RUN"}, {"FIREBIRD_WRITES": "0", "FISCAL_MODE": "AUTO_APPLY"}, {"FIREBIRD_WRITES": "1", "FISCAL_MODE": "dry_run"}):
+        cfg = service.Config({"FIREBIRD_DATABASE_PATH": "x.fdb", **extra})
+        assert cfg.firebird_writes is False
+    assert service.Config({"FIREBIRD_DATABASE_PATH": "x.fdb", "FIREBIRD_WRITES": "1", "FISCAL_MODE": "AUTO_APPLY"}).firebird_writes is True
+    assert service.Config({"FIREBIRD_DATABASE_PATH": "x.fdb", "FIREBIRD_WRITES": "1"}).firebird_writes is True  # legacy: unset FISCAL_MODE follows the flag
+    assert service.Config({"FIREBIRD_DATABASE_PATH": "x.fdb"}).fiscal_mode == "DRY_RUN"
+
+
+def test_write_connection_cannot_be_opened_when_writes_are_disabled(monkeypatch):
+    opened = []
+    monkeypatch.setitem(sys.modules, "fdb", type("F", (), {"connect": staticmethod(lambda **kw: opened.append(kw))}))
+    with pytest.raises(RuntimeError):
+        service.open_write_connection({"FB_USER": "u", "FB_PASSWORD": "SECRETPASSVALUE9"}, "x.fdb", firebird_writes=False)
+    assert opened == []
+
+
+def test_dry_run_job_never_opens_a_write_connection_nor_calls_the_executor(monkeypatch):
+    class Boom:
+        def __getattr__(self, name):
+            if name in ("execute_guarded_update", "execute_guarded_restore"):
+                raise AssertionError("executor write called in DRY_RUN")
+            return getattr(__import__("scripts.firebird_write_executor", fromlist=["x"]) if False else object(), name, None)
+    cfg = service.Config({"FIREBIRD_DATABASE_PATH": "x.fdb", "FIREBIRD_WRITES": "1", "FISCAL_MODE": "DRY_RUN"})
+    monkeypatch.setattr(service, "read_products", lambda env, codigos=None: [{"CODIGO": "000001", "PRODUTO": "X", "CLASSIFICACAO_FISCAL": "22030000", "IPI": None}])
+    monkeypatch.setattr(service, "HubClient", lambda url, token: type("H", (), {"classify_batch": lambda self, p: [{"status": "EXACT_NCM", "ipi_status": "IPI_RESOLVED", "classification": {"ipi": {"rate_kind": "NUMERIC", "rate_numeric": 3.9}},
+                                                                                                                  "dataset_versions": {}}]})())
+    monkeypatch.setattr(service, "build_job_coverage", lambda *a, **k: {"TOTAL_PRODUCTS": 1})
+    monkeypatch.setattr(service, "open_write_connection", lambda *a, **k: (_ for _ in ()).throw(AssertionError("write connection opened in DRY_RUN")))
+
+    class State:
+        def log_ipi_write(self, *a): pass
+
+    class Ex:
+        WriteRefused = Exception
+        def execute_guarded_update(self, *a, **k): raise AssertionError("executor write called in DRY_RUN")
+
+    result, error = service.execute_job({"kind": "REPROCESS_ALL", "agent_id": 1, "payload": {}, "job_id": 1}, cfg, Ex(), State(), {})
+    assert error is None and result["writes_attempted"] == 0 and result["firebird_writes_enabled"] is False

agent/tests/test_run_agent_service.py

@@ -0,0 +1,272 @@
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPT = Path(__file__).parents[1] / "scripts" / "run_agent_service.py"
+AUTHORIZED = r"D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("run_agent_service", SCRIPT)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+service = load_module()
+
+
+class _FakeState:
+    def __init__(self):
+        self.logged = []
+
+    def log_ipi_write(self, *args):
+        self.logged.append(args)
+
+
+class _FakeExecutor:
+    """Mirrors the real firebird_write_executor's public surface used by execute_job."""
+    class WriteRefused(Exception):
+        pass
+
+    def __init__(self, path_guard_ok=True, updates=None, fingerprint_guard_ok=True):
+        self.path_guard_ok = path_guard_ok
+        self.updates = updates or {}
+        self.fingerprint_guard_ok = fingerprint_guard_ok
+
+    def assert_authorized_write_path(self, path, authorized_path=None):
+        if not self.path_guard_ok:
+            raise self.WriteRefused(f"path is not the authorized write target: {path}")
+
+    def assert_schema_fingerprint_authorized(self, observed, expected):
+        if not self.fingerprint_guard_ok or observed != expected:
+            raise self.WriteRefused(f"schema fingerprint mismatch: expected {expected!r}, observed {observed!r}")
+
+    def execute_guarded_update(self, connection, *, database_path, proposal, now, authorized_path=None):
+        code = proposal["product_code"]
+        if code in self.updates:
+            raise self.WriteRefused(self.updates[code])
+        record = type("Record", (), {
+            "before_value": proposal["current_value"],
+            "after_value": proposal["proposed_value"],
+            "rowcount": 1,
+        })()
+        return record
+
+
+def _config(**overrides):
+    base = dict(
+        hub_url="http://localhost:8000", agent_id="a1", agent_token="tok", company_id="c1", company_uf="BA",
+        database_path=AUTHORIZED, firebird_writes=False, poll_interval_seconds=0.01,
+        agent_version="0.1.0", schema_fingerprint="fp", state_db=":memory:",
+        authorized_write_database_path=None, expected_schema_fingerprint="fp",
+    )
+    base.update(overrides)
+    return type("Config", (), base)()
+
+
+def test_config_defaults_from_env():
+    env = {"FIREBIRD_DATABASE_PATH": AUTHORIZED}
+    config = service.Config(env)
+    assert config.firebird_writes is False
+    assert config.hub_url == "http://localhost:8000"
+    assert config.poll_interval_seconds == 5.0
+
+
+def test_config_reads_gti_hub_url_and_writes_flag():
+    env = {"FIREBIRD_DATABASE_PATH": AUTHORIZED, "GTI_HUB_URL": "http://hub.internal", "FIREBIRD_WRITES": "1"}
+    config = service.Config(env)
+    assert config.hub_url == "http://hub.internal"
+    assert config.firebird_writes is True
+
+
+def test_path_guard_fails_closed_before_any_write(monkeypatch):
+    config = _config(firebird_writes=True, database_path=r"D:\PRODUCAO\ERP.FDB")
+    executor = _FakeExecutor(path_guard_ok=False)
+    state = _FakeState()
+    job = {"kind": "REPROCESS_PRODUCTS", "agent_id": 1, "payload": {"codigos": ["000026"]}}
+
+    called = {"read_products": False}
+
+    def fake_read_products(env, codigos=None):
+        called["read_products"] = True
+        return []
+
+    monkeypatch.setattr(service, "read_products", fake_read_products)
+    result, error = service.execute_job(job, config, executor, state, {})
+    assert result is None
+    assert "not the authorized write target" in error
+    assert called["read_products"] is False  # never even reads Firebird once the guard refuses
+
+
+def test_pilot_write_blocked_when_schema_fingerprint_does_not_match(monkeypatch):
+    # A real client install where the live schema fingerprint drifted from what
+    # this Agent installation was configured/registered to expect.
+    config = _config(firebird_writes=True, schema_fingerprint="observed-live-fp", expected_schema_fingerprint="registered-fp")
+    executor = _FakeExecutor()
+    state = _FakeState()
+    job = {"kind": "REPROCESS_PRODUCTS", "agent_id": 1, "payload": {"codigos": ["000026"]}}
+
+    called = {"read_products": False}
+    monkeypatch.setattr(service, "read_products", lambda env, codigos=None: called.update(read_products=True) or [])
+
+    result, error = service.execute_job(job, config, executor, state, {})
+    assert result is None
+    assert "schema fingerprint mismatch" in error
+    assert called["read_products"] is False
+
+
+def test_pilot_write_allowed_with_explicit_authorized_path_and_matching_fingerprint(monkeypatch):
+    client_path = r"D:\ClienteX\ERP\PRODUCAO.FDB"
+    config = _config(
+        firebird_writes=True, database_path=client_path, authorized_write_database_path=client_path,
+        schema_fingerprint="fp", expected_schema_fingerprint="fp",
+    )
+    products = [{"CODIGO": "000026", "PRODUTO": "x", "CLASSIFICACAO_FISCAL": "03055100", "IPI": None}]
+    decisions = [{
+        "status": "EXACT_NCM", "ipi_status": "IPI_RESOLVED",
+        "classification": {"ipi": {"rate_kind": "NUMERIC", "rate_numeric": 3.25}},
+        "dataset_versions": {"tipi_ipi": "v1"},
+    }]
+    monkeypatch.setattr(service, "read_products", lambda env, codigos=None: products)
+
+    class FakeClient:
+        def __init__(self, *a, **k): pass
+        def classify_batch(self, items): return decisions
+    monkeypatch.setattr(service, "HubClient", FakeClient)
+    fake_connection = type("Conn", (), {"close": lambda self: None})()
+    monkeypatch.setattr(service, "open_write_connection", lambda env, path: fake_connection)
+
+    executor = _FakeExecutor()
+    state = _FakeState()
+    job = {"kind": "REPROCESS_PRODUCTS", "agent_id": 1, "payload": {"codigos": ["000026"]}}
+
+    result, error = service.execute_job(job, config, executor, state, {})
+    assert error is None
+    assert result["writes_succeeded"] == 1
+
+
+def test_execute_job_isolates_internal_errors_without_raising(monkeypatch):
+    config = _config()
+
+    def boom(env, codigos=None):
+        raise RuntimeError("firebird unavailable")
+
+    monkeypatch.setattr(service, "read_products", boom)
+    executor = _FakeExecutor()
+    state = _FakeState()
+    job = {"kind": "REPROCESS_ALL", "agent_id": 1, "payload": {}}
+
+    result, error = service.execute_job(job, config, executor, state, {})
+    assert result is None
+    assert "firebird unavailable" in error
+
+
+def test_execute_job_success_summarizes_pipeline(monkeypatch):
+    config = _config()
+    products = [{"CODIGO": "000026", "PRODUTO": "x", "CLASSIFICACAO_FISCAL": "03055100", "IPI": None}]
+    decisions = [{
+        "status": "EXACT_NCM", "ipi_status": "IPI_RESOLVED",
+        "classification": {"ipi": {"rate_kind": "NUMERIC", "rate_numeric": 3.25}},
+        "dataset_versions": {"tipi_ipi": "v1"},
+    }]
+
+    monkeypatch.setattr(service, "read_products", lambda env, codigos=None: products)
+
+    class FakeClient:
+        def __init__(self, *a, **k): pass
+        def classify_batch(self, items): return decisions
+    monkeypatch.setattr(service, "HubClient", FakeClient)
+
+    executor = _FakeExecutor()
+    state = _FakeState()
+    job = {"kind": "REPROCESS_PRODUCTS", "agent_id": 1, "payload": {"codigos": ["000026"]}}
+
+    result, error = service.execute_job(job, config, executor, state, {})
+    assert error is None
+    assert result["products_processed"] == 1
+    assert result["writes_attempted"] == 0  # firebird_writes disabled by default in _config()
+
+
+class _FakeHubForLoop:
+    """Simulates: heartbeat flaky twice then OK, one job then nothing, and captures completions."""
+
+    def __init__(self):
+        self.heartbeat_calls = 0
+        self.jobs = [{"job_id": 1, "kind": "REPROCESS_ALL", "agent_id": 1, "payload": {}}]
+        self.completed = []
+        self.failed = []
+
+    def heartbeat(self, *a, **k):
+        self.heartbeat_calls += 1
+        if self.heartbeat_calls == 1:
+            raise ConnectionError("hub down")
+        return {}
+
+    def next_job(self):
+        return self.jobs.pop(0) if self.jobs else None
+
+    def complete_job(self, job_id, result_summary):
+        self.completed.append((job_id, result_summary))
+
+    def fail_job(self, job_id, error):
+        self.failed.append((job_id, error))
+
+    def classify_batch(self, items):
+        return []
+
+
+class _ExternalStopFlag:
+    """Mirrors the Windows Service wrapper's stop object: no signal registration,
+    just a plain flag flippable from another thread."""
+    def __init__(self):
+        self.stop = False
+
+
+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
+    # passes its own stop flag and flips it from the SvcStop handler.
+    config = _config(poll_interval_seconds=0.001)
+    fake_hub = _FakeHubForLoop()
+    fake_hub.jobs = []  # no jobs; loop would run forever without an external stop
+    monkeypatch.setattr(service, "HubClient", lambda *a, **k: fake_hub)
+    monkeypatch.setattr(service, "load_executor", lambda: _FakeExecutor())
+    monkeypatch.setattr(service, "AgentState", lambda path: _FakeState())
+    monkeypatch.setattr(service, "read_products", lambda env, codigos=None: [])
+
+    stopper = _ExternalStopFlag()
+    calls = {"n": 0}
+    real_sleep = service.time.sleep
+
+    def counting_sleep(seconds):
+        calls["n"] += 1
+        if calls["n"] >= 3:
+            stopper.stop = True
+
+    monkeypatch.setattr(service.time, "sleep", counting_sleep)
+    service.run(config, {}, stopper=stopper)  # no max_iterations — only the external flag can stop it
+    assert stopper.stop is True
+    assert calls["n"] >= 3
+
+
+def test_run_survives_hub_down_then_processes_one_job_and_stops(monkeypatch):
+    config = _config(poll_interval_seconds=0.001)
+    fake_hub = _FakeHubForLoop()
+    monkeypatch.setattr(service, "HubClient", lambda *a, **k: fake_hub)
+    monkeypatch.setattr(service, "load_executor", lambda: _FakeExecutor())
+    monkeypatch.setattr(service, "AgentState", lambda path: _FakeState())
+    monkeypatch.setattr(service, "read_products", lambda env, codigos=None: [])
+    monkeypatch.setattr(service, "build_job_coverage", lambda *a, **k: None)
+    monkeypatch.setattr(service.time, "sleep", lambda seconds: None)
+
+    # first heartbeat call raises -> backoff branch; second call onward succeeds.
+    service.run(config, {}, max_iterations=4)
+
+    assert fake_hub.heartbeat_calls >= 2
+    assert len(fake_hub.completed) == 1
+    assert fake_hub.completed[0][0] == 1
+    assert fake_hub.completed[0][1]["products_processed"] == 0

agent/tests/test_runner_mapping.py

@@ -0,0 +1,7 @@
+from gti_fiscal_agent.runner import to_hub_product
+
+
+def test_reference_schema_uses_classificacao_fiscal_as_canonical_ncm():
+    product = {"CODIGO": "000276", "PRODUTO": "ABACAXI M/ JARRA", "NCM": "99999999", "CLASSIFICACAO_FISCAL": "08043000"}
+
+    assert to_hub_product(product)["current_ncm"] == "08043000"

agent/tests/test_state.py

@@ -0,0 +1,20 @@
+from gti_fiscal_agent.state import AgentState
+
+
+def test_outbox_keeps_failed_work_pending(tmp_path):
+    state = AgentState(tmp_path / "agent.db")
+    assert state.enqueue("000276", "source", "v1", "0.1.0")
+    state.retry("000276")
+    assert state.pending()[0]["status"] == "PENDING_API"
+    state.result_received("000276", "source", "v1", "0.1.0")
+    assert state.enqueue("000276", "source", "v1", "0.1.0") is False
+
+
+def test_ipi_write_log_records_per_product_audit(tmp_path):
+    state = AgentState(tmp_path / "agent.db")
+    state.log_ipi_write("000276", "fp1", "EXACT_NCM", "IPI_RESOLVED", "SUCCEEDED", None, 3.25, "rowcount=1", "CHANGE_REQUIRED", "2026-09-18T00:00:00Z")
+    log = state.ipi_write_log_for("000276")
+    assert len(log) == 1
+    assert log[0]["write_status"] == "SUCCEEDED"
+    assert log[0]["before_value"] is None
+    assert log[0]["proposed_value"] == "3.25"