feat: TECHNICAL_PLACEHOLDER (NCM 00000000) is replaceable by the product enrichment; real values preserved; Agent 1.3.4

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

agent/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gti-fiscal-agent"
-version = "1.3.3"
+version = "1.3.4"
 requires-python = ">=3.10"
 dependencies = ["httpx>=0.27,<1"]
 

agent/scripts/run_agent_service.py

@@ -107,7 +107,7 @@ class Config:
         self.poll_interval_seconds = float(env.get("POLL_INTERVAL_SECONDS", "5"))
         # RTC auto-apply is a SEPARATE switch (default OFF): FIREBIRD_WRITES alone never lets the Agent fill cClassTrib.
         self.rtc_auto_apply_max_per_job = int(env.get("RTC_AUTO_APPLY_MAX_PER_JOB", str(_rtc_apply.DEFAULT_MAX_PER_JOB)))
-        self.agent_version = env.get("AGENT_VERSION", "1.3.3")
+        self.agent_version = env.get("AGENT_VERSION", "1.3.4")
         self.schema_fingerprint = env.get("SCHEMA_FINGERPRINT", REFERENCE_SCHEMA_V1)
         self.state_db = env.get("AGENT_STATE_DB", str(AGENT_ROOT / "agent_state.sqlite"))
         # Pilot write authorization: both must be explicitly set by the installer for
@@ -349,7 +349,7 @@ def execute_job(job, config, executor, state, env):
             "fiscal_context": fiscal_context,
             "rtc_auto_apply": rtc_apply,
             "fiscal_mode": getattr(config, "fiscal_mode", None),
-            "release_version": env.get("AGENT_VERSION") or "1.3.3",
+            "release_version": env.get("AGENT_VERSION") or "1.3.4",
             "products_total": len(products),
             "products_changed": len(to_process),
             "products_processed": summary["processed"],
@@ -520,7 +520,7 @@ def run(config, env, *, max_iterations=None, stopper=None):
 def enforce_startup_preflight(env):
     """Full read-only preflight at startup (Hub, auth, Firebird, capabilities, company context, guards). Fail closed."""
     from gti_fiscal_agent.preflight import run_preflight
-    report = run_preflight(env, agent_version=env.get("AGENT_VERSION") or "1.3.3")
+    report = run_preflight(env, agent_version=env.get("AGENT_VERSION") or "1.3.4")
     logger.info("startup preflight: %s", json.dumps({k: report[k] for k in ("PREFLIGHT", "blockers", "fiscal_mode", "effective_firebird_writes")}, ensure_ascii=False))
     print(json.dumps({"PREFLIGHT": report["PREFLIGHT"], "blockers": report["blockers"]}, ensure_ascii=False))
     if report["PREFLIGHT"] != "PASS":

agent/src/gti_fiscal_agent/enrichment.py

@@ -21,7 +21,10 @@ from datetime import datetime, timezone
 logger = logging.getLogger("gti_fiscal_agent.enrichment")
 
 CAPABILITY = "PRODUCT_ENRICHMENT_WRITE_V1"
-ALLOWED_FIELDS = ("CLASSIFICACAO_FISCAL", "CEST", "IPI")            # explicit allowlist; anything else raises before touching SQL
+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
 POLL_SECONDS = 2.0
 SAFETY_DIFF_SECONDS = 60.0
@@ -108,6 +111,16 @@ def is_human_overridden(store_path, code, field) -> bool:
 
 
 # ---- Firebird access (injected: `read_conn()` returns a READ-ONLY connection, `write_conn()` a write-capable one, only ever opened by ENABLED mode) ----------------------------------------
+def is_placeholder(field, value) -> bool:
+    text = _text(value)
+    text = "".join(ch for ch in text if ch.isdigit()) if field == "CLASSIFICACAO_FISCAL" else text
+    return text in PLACEHOLDERS.get(field, frozenset())
+
+
+def writable_now(field, value) -> bool:
+    return not _text(value) or is_placeholder(field, value)
+
+
 def _digits(value) -> str:
     return "".join(ch for ch in _text(value) if ch.isdigit())
 
@@ -174,10 +187,14 @@ def write_field(conn, code: str, field: str, value) -> dict:
         if len(rows) != 1:
             conn.rollback()
             return {"outcome": "ABORTED", "reason": "PRODUCT_ROW_NOT_UNIQUE" if rows else "PRODUCT_NOT_FOUND"}
-        if _text(rows[0][0]):
+        raw = rows[0][0]
+        if not writable_now(field, raw):
             conn.rollback()
             return {"outcome": "ABORTED", "reason": "VALUE_ALREADY_SET_NEVER_OVERWRITTEN"}
-        cur.execute(f"UPDATE C000025 SET {field} = ? WHERE CODIGO = ? AND ({field} IS NULL OR TRIM({field}) = '')", (value, code))
+        if _text(raw):                                               # technical placeholder: compare-and-swap on the exact value just read
+            cur.execute(f"UPDATE C000025 SET {field} = ? WHERE CODIGO = ? AND TRIM({field}) = ?", (value, code, _text(raw)))
+        else:
+            cur.execute(f"UPDATE C000025 SET {field} = ? WHERE CODIGO = ? AND ({field} IS NULL OR TRIM({field}) = '')", (value, code))
         if cur.rowcount != 1:
             conn.rollback()
             return {"outcome": "ABORTED", "reason": "UPDATE_ROWCOUNT_NOT_ONE"}
@@ -189,7 +206,7 @@ def write_field(conn, code: str, field: str, value) -> dict:
         same = (float(after) == value) if field == "IPI" and after is not None else _text(after) == value
         if not same:
             return {"outcome": "FAILED", "reason": "POST_WRITE_VERIFICATION_FAILED"}
-        return {"outcome": "APPLIED", "value": value, "rowcount": 1}
+        return {"outcome": "APPLIED", "value": value, "rowcount": 1, "replaced_placeholder": _text(raw) if _text(raw) else None}
     except Exception as error:  # noqa: BLE001
         try:
             conn.rollback()
@@ -345,7 +362,8 @@ class EnrichmentWorker:
         for field in ALLOWED_FIELDS:
             decision = fields.get(field) or {}
             status, value = decision.get("status"), decision.get("value")
-            base = {"field": field, "rule": decision.get("rule"), "kb_status": decision.get("kb_status"), "evidence": decision.get("evidence") or [], "old": None, "new": value}
+            placeholder = _text(current.get(field)) if is_placeholder(field, current.get(field)) else None
+            base = {"field": field, "rule": decision.get("rule"), "kb_status": decision.get("kb_status"), "evidence": decision.get("evidence") or [], "old": placeholder, "new": value}
             if status == "HUMAN_OVERRIDDEN" or overridden.get(field):
                 reports.append({**base, "outcome": "HUMAN_OVERRIDDEN", "reason": "HUMAN_OVERRIDDEN", "new": None})
                 continue

agent/src/gti_fiscal_agent/preflight.py

@@ -9,7 +9,7 @@ import os
 import sqlite3
 from pathlib import Path
 
-AGENT_VERSION_DEFAULT = "1.3.3"
+AGENT_VERSION_DEFAULT = "1.3.4"
 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")

agent/tests/test_enrichment.py

@@ -45,7 +45,7 @@ class Hub:
         for f in list(fields):
             if f in self.overridden.get(payload["product_code"], set()):
                 fields[f] = {"status": "HUMAN_OVERRIDDEN", "value": None}
-            elif payload["current"].get(f):
+            elif payload["current"].get(f) and not E.is_placeholder(f, payload["current"].get(f)):
                 fields[f] = {"status": "ALREADY_SET", "value": None}
         return {"state": self.state, "fields": fields, "dataset_versions": {"NCM": {"sha256": "abc"}}}
 
@@ -230,3 +230,68 @@ def test_products_created_while_inactive_are_not_new_when_reactivated(env):
     add(db, "W2")
     now[0] += 5
     assert worker.step() == ["W2"]
+
+
+# ---- TECHNICAL_PLACEHOLDER (the SGV refuses a product without NCM: operators type 00000000) ---------------------------------------------------
+def add_with_ncm(db, code, ncm, name="COCA-COLA ORIGINAL LATA 350 ML"):
+    db.execute("INSERT INTO C000025(CODIGO,PRODUTO,GTIN,CLASSIFICACAO_FISCAL,OTHER) VALUES(?,?,?,?,?)", (code, name, "7891000100103", ncm, "keep"))
+    db.commit()
+
+
+def test_placeholder_parity_with_the_hub():
+    sys.path.insert(0, str(ROOT))
+    from central.app.enrichment import placeholders as hub
+    assert {k: set(v) for k, v in E.PLACEHOLDERS.items()} == {k: set(v) for k, v in hub.PRODUCT_ENRICHMENT_PLACEHOLDERS.items()}
+    for value in ("00000000", "0000.00.00", " 00000000 ", "22021000", "99999999", "0", "SEM NCM", "", None):
+        assert E.is_placeholder("CLASSIFICACAO_FISCAL", value) == hub.is_placeholder("CLASSIFICACAO_FISCAL", value), value
+    assert not E.is_placeholder("CEST", "0000000") and not E.is_placeholder("IPI", 0)
+
+
+def test_placeholder_ncm_is_replaced_dry_run_first_then_enabled_and_second_run_is_zero(env):
+    db, hub, store, worker, now, _ = env
+    hub.features = {"features_configured": True, "enrichment_mode": "DRY_RUN"}
+    worker._features_at = -999
+    worker.step()                                                    # baseline
+    add_with_ncm(db, "P1", "00000000")
+    now[0] += 5
+    worker.step()
+    assert row(db, "P1")[0] == "00000000" and hub.reports[-1]["fields"][0]["outcome"] == "DRY_RUN"       # DRY_RUN: detected, zero writes
+    assert hub.resolve_calls[-1]["current"]["CLASSIFICACAO_FISCAL"] == "00000000"
+    hub.features = dict(ENABLED)
+    worker._features_at = -999
+    worker._auth_cache = (None, 0.0)
+    add_with_ncm(db, "P2", "00000000")
+    now[0] += 5
+    worker.step()
+    assert row(db, "P2") == ("22021000", "0300700", 0.0, "keep")
+    first = [f for f in hub.reports[-1]["fields"] if f["field"] == "CLASSIFICACAO_FISCAL"][0]
+    assert first["outcome"] == "APPLIED" and first["old"] == "00000000"
+    before = db.total_changes
+    now[0] += 5
+    worker.step()
+    now[0] += 60
+    worker.step()
+    assert db.total_changes == before                                # second run: 0 writes
+
+
+def test_real_or_unlisted_ncm_is_never_replaced(env):
+    db, hub, store, worker, now, _ = env
+    worker.step()
+    for code, ncm in (("R1", "22021000"), ("R2", "99999999"), ("R3", "0"), ("R4", "SEM NCM"), ("R5", "19059090")):
+        add_with_ncm(db, code, ncm)
+    now[0] += 5
+    worker.step()
+    for code, ncm in (("R1", "22021000"), ("R2", "99999999"), ("R3", "0"), ("R4", "SEM NCM"), ("R5", "19059090")):
+        assert row(db, code)[0] == ncm, code                          # EXISTING_REAL_VALUE_PRESERVED, even if the KB says otherwise
+
+
+def test_write_field_guards_the_placeholder_swap():
+    db = sqlite3.connect(":memory:")
+    db.execute("CREATE TABLE C000025(CODIGO TEXT, CLASSIFICACAO_FISCAL TEXT)")
+    db.executemany("INSERT INTO C000025 VALUES(?,?)", [("a", "00000000"), ("b", "22021000"), ("c", None), ("d", "0000.00.00")])
+    db.commit()
+    assert E.write_field(Conn(db), "a", "CLASSIFICACAO_FISCAL", "19059090")["outcome"] == "APPLIED"
+    assert E.write_field(Conn(db), "b", "CLASSIFICACAO_FISCAL", "19059090")["reason"] == "VALUE_ALREADY_SET_NEVER_OVERWRITTEN"
+    assert E.write_field(Conn(db), "c", "CLASSIFICACAO_FISCAL", "19059090")["outcome"] == "APPLIED"
+    assert E.write_field(Conn(db), "d", "CLASSIFICACAO_FISCAL", "19059090")["outcome"] == "APPLIED"
+    assert [r[0] for r in db.execute("SELECT CLASSIFICACAO_FISCAL FROM C000025 ORDER BY CODIGO")] == ["19059090", "22021000", "19059090", "19059090"]