Add 'fiscal/' from commit '102ba84500dbd9655a0471288c3e278652593ca9'

git-subtree-dir: fiscal
git-subtree-mainline: d95165fc8f
git-subtree-split: 102ba84500

fiscal/scripts/analyze_erp_fiscal_history.py

@@ -0,0 +1,129 @@
+"""Read-only historical fiscal analysis over TESTESOFICIAIS.FDB: correlates emitted
+NFC-e items (NFCE_ITENS) and sale/purchase item tables with C000025 product defaults.
+No DML/DDL. Output: docs/runs/erp_fiscal_history_analysis.json
+"""
+import json, os, sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+from gti_fiscal_agent.firebird_reader import _connect  # noqa: E402
+
+for l in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+    if "=" in l and not l.startswith("#"):
+        k, _, v = l.partition("="); os.environ.setdefault(k.strip(), v.strip())
+
+
+def s(v):
+    return None if v is None else str(v).strip()
+
+
+def digits(v):
+    return "".join(c for c in str(v or "") if c.isdigit())
+
+
+def main():
+    conn = _connect(os.environ); cur = conn.cursor()
+    cur.execute("select CODIGO, CFOP, CST, CSOSN, GRUPO_ICMS, CEST, CLASSIFICACAO_FISCAL, COD_SAIDA_PIS, INCIDENCIA_PISCOFINS, ALIQUOTA from C000025")
+    prod = {s(r[0]): dict(zip(("CFOP", "CST", "CSOSN", "GRUPO_ICMS", "CEST", "NCM", "PIS", "INC", "ALIQ"), map(s, r[1:]))) for r in cur.fetchall()}
+
+    res = {"products": len(prod)}
+    cur.execute("select min(DATA), max(DATA), count(*) from NFCE_ITENS"); mn, mx, n = cur.fetchone()
+    res["nfce_itens"] = {"rows": n, "date_min": str(mn), "date_max": str(mx)}
+    cur.execute("select count(*), min(DATA), max(DATA) from NFCE"); r = cur.fetchone(); res["nfce_docs"] = {"rows": r[0], "min": str(r[1]), "max": str(r[2])}
+
+    cur.execute("select CODPRODUTO, CFOP, CST, GRUPO_ICMS, CSOSN, NCM, CEST, CST_PIS_COFINS, ALIQUOTA, VALOR from NFCE_ITENS")
+    rows = cur.fetchall()
+    joined = 0; agree = defaultdict(Counter); per_prod = defaultdict(lambda: defaultdict(Counter)); orphan = 0
+    for cod, cfop, cst, gicms, csosn, ncm, cest, pispc, aliq, val in rows:
+        p = prod.get(s(cod))
+        if p is None:
+            orphan += 1; continue
+        joined += 1
+        item = {"CFOP": s(cfop), "CST": s(cst), "GRUPO_ICMS": s(gicms), "CSOSN": s(csosn), "NCM": s(ncm), "CEST": s(cest), "PIS": s(pispc)}
+        for f, iv in item.items():
+            if iv is None:
+                agree[f]["ITEM_NULL"] += 1; continue
+            pv = p.get(f if f != "PIS" else "PIS")
+            if f == "CEST":
+                agree[f]["MATCH" if digits(iv) == digits(pv) else "MISMATCH"] += 1
+            elif f == "PIS":
+                agree[f]["MATCH" if iv.lstrip("0") == (pv or "").lstrip("0") else "MISMATCH"] += 1
+            else:
+                agree[f]["MATCH" if iv == pv else "MISMATCH"] += 1
+            per_prod[s(cod)][f][iv] += 1
+    res["nfce_join"] = {"items_joined_to_C000025": joined, "orphan_items": orphan,
+                        "agreement_item_vs_product_default": {f: dict(c) for f, c in agree.items()}}
+    res["nfce_products_seen"] = len(per_prod)
+    res["variability"] = {f: sum(1 for pp in per_prod.values() if len(pp[f]) > 1) for f in ("CFOP", "CST", "GRUPO_ICMS", "CSOSN", "CEST", "NCM")}
+    res["nfce_item_value_distributions"] = {}
+    for f, idx in (("CFOP", 1), ("CST", 2), ("GRUPO_ICMS", 3), ("CSOSN", 4), ("CST_PIS_COFINS", 7)):
+        res["nfce_item_value_distributions"][f] = Counter(s(r[idx]) for r in rows).most_common(8)
+
+    # Sale/purchase item tables (C000032 sales, C000062 purchase items) vs product defaults
+    for table, extra in (("C000032", "CST, CFOP"), ("C000062", "CST, CFOP")):
+        cur.execute(f"select CODPRODUTO, {extra} from {table}")
+        c = Counter(); cfopc = Counter(); cstc = Counter()
+        for cod, cst, cfop in cur.fetchall():
+            p = prod.get(s(cod))
+            if p is None: c["ORPHAN"] += 1; continue
+            c["JOINED"] += 1
+            if s(cst): cstc["MATCH" if s(cst) == p["CST"] else "MISMATCH"] += 1
+            if s(cfop): cfopc["MATCH" if s(cfop) == p["CFOP"] else "MISMATCH"] += 1
+        res[table] = {"joined": dict(c), "cst_vs_product": dict(cstc), "cfop_vs_product": dict(cfopc)}
+
+    # Natureza de operação (C000030) and operation-context sources
+    cur.execute("select TIPO, count(*) from C000030 group by TIPO"); res["C000030_tipo"] = dict(cur.fetchall())
+    cur.execute("select substring(CFOP from 1 for 1), count(*) from C000030 group by 1 order by 1"); res["C000030_cfop_first_digit"] = dict(cur.fetchall())
+    cur.execute("select CFOP from C000030 where CFOP in ('5102','5405','5656','5929','6102','1102')"); res["C000030_has_cfops"] = [s(r[0]) for r in cur.fetchall()]
+    cur.execute("select IND_CFOP_ENTRADA, IND_CFOP_SAIDA, IND_CFOP_PERDA from C000001"); res["C000001_cfop_defaults"] = [s(x) for x in cur.fetchone()]
+    cur.execute("select OPTANTE_SIMPLES, OPTANTE_SUPER_SIMPLES, CRT, ICMS_CSOSN, SUBSTITUTO_TRIBUTARIO, CONTRIBUINTE_IPI, UF from C000004"); res["C000004"] = [s(x) for x in cur.fetchone()]
+    cur.execute("select EMITENTE_CRT from EMISSOR"); res["EMISSOR_CRT"] = [s(x) for x in cur.fetchone()]
+    cur.execute("select CFOP, count(*) from C000062 group by CFOP"); res["C000062_cfop"] = {s(a): b for a, b in cur.fetchall()}
+    cur.execute("select CST, count(*) from C000062 group by CST"); res["C000062_cst"] = {s(a): b for a, b in cur.fetchall()}
+    cur.execute("select count(*), sum(case when MARGEM_AGREGADA <> 0 then 1 else 0 end), sum(case when ICMS_SUB <> 0 then 1 else 0 end) from C000062"); res["C000062_mva_usage"] = list(cur.fetchone())
+    cur.execute("select count(*) from PRODUTOS_MARGEM_AGREGADA"); res["PRODUTOS_MARGEM_AGREGADA_rows"] = cur.fetchone()[0]
+    cur.execute("select count(*) from C000025 where MARGEM_AGREGADA is not null"); res["C000025_MARGEM_AGREGADA_nonnull"] = cur.fetchone()[0]
+
+    # CEST history for the 15 CEST-candidate products (from the decision matrix)
+    matrix = json.loads((ROOT / "docs" / "FISCAL_DECISION_MATRIX_V1.json").read_text(encoding="utf-8"))
+    cand = [m for m in matrix["products"] if m["fields"]["CEST"]["status"] == "RULE_CANDIDATE"]
+    cest_hist = []
+    for m in cand:
+        code = s(m["CODIGO"])
+        hist = Counter(digits(k) for k, c in per_prod.get(code, {}).get("CEST", {}).items() for _ in range(c) if digits(k))
+        cest_hist.append({"CODIGO": code, "DESCRIPTION": m["DESCRIPTION"], "NCM": m["NCM"], "erp_current_cest": m["fields"]["CEST"]["current_value"], "historical_cest": dict(hist)})
+    res["cest_candidates_history"] = cest_hist
+    conn.close()
+
+    # Shadow validation: decision matrix engine value vs historical NFC-e item value
+    val = {}
+    for dom, hist_field in (("NCM", "NCM"), ("CEST", "CEST"), ("CFOP", "CFOP"), ("CST_ICMS", "CST"), ("CSOSN", "CSOSN"), ("PIS_CST", "PIS")):
+        val[dom] = Counter()
+    by_code = {s(m["CODIGO"]): m["fields"] for m in matrix["products"]}
+    conn = _connect(os.environ); cur = conn.cursor()
+    cur.execute("select first 5000 CODPRODUTO, NCM, CEST, CFOP, CST, CSOSN, CST_PIS_COFINS from NFCE_ITENS where NCM is not null")
+    n_sim = 0
+    for cod, ncm, cest, cfop, cst, csosn, pispc in cur.fetchall():
+        f = by_code.get(s(cod))
+        if f is None: continue
+        n_sim += 1
+        hist = {"NCM": s(ncm), "CEST": s(cest), "CFOP": s(cfop), "CST_ICMS": s(cst), "CSOSN": s(csosn), "PIS_CST": s(pispc)}
+        for dom, hv in hist.items():
+            rec = f[dom]
+            ev = rec["proposed_value"] if rec["status"] == "RULE_RESOLVED" else None
+            if rec["status"] == "RULE_RESOLVED" and dom == "NCM":
+                ev = rec["current_value"]
+            if ev is None:
+                val[dom]["UNRESOLVED"] += 1
+            elif digits(ev) == digits(hv) if dom in ("NCM", "CEST") else str(ev) == str(hv):
+                val[dom]["MATCH"] += 1
+            else:
+                val[dom]["MISMATCH"] += 1
+    res["shadow_validation"] = {"items": n_sim, **{d: dict(c) for d, c in val.items()}}
+    conn.close()
+    print(json.dumps(res, ensure_ascii=False, indent=1, default=str))
+
+
+main()

fiscal/scripts/analyze_erp_fiscal_history_extra.py

@@ -0,0 +1,61 @@
+"""Read-only extras: (1) history agreement restricted to identity-consistent joins (item NCM == product NCM),
+(2) CEST historical support for the CEST-candidate products against the Hub's official candidates."""
+import json, os, sys, urllib.request
+from collections import Counter
+from pathlib import Path
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+from gti_fiscal_agent.firebird_reader import _connect
+for l in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+    if "=" in l and not l.startswith("#"):
+        k, _, v = l.partition("="); os.environ.setdefault(k.strip(), v.strip())
+s = lambda v: None if v is None else str(v).strip()
+dg = lambda v: "".join(c for c in str(v or "") if c.isdigit())
+c = _connect(os.environ).cursor()
+c.execute("select CODIGO, PRODUTO, CLASSIFICACAO_FISCAL, CFOP, CST, CSOSN, CEST, COD_SAIDA_PIS from C000025")
+P = {s(r[0]): dict(zip(("D", "NCM", "CFOP", "CST", "CSOSN", "CEST", "PIS"), map(s, r[1:]))) for r in c.fetchall()}
+c.execute("select CODPRODUTO, NCM, CFOP, CST, CSOSN, CEST, CST_PIS_COFINS, GRUPO_ICMS from NFCE_ITENS where NCM is not null")
+consistent = Counter(); inconsistent = 0; agree = {f: Counter() for f in ("CFOP", "CST", "CSOSN", "CEST", "PIS")}
+hist_cest = {}
+for cod, ncm, cfop, cst, csosn, cest, pis, gi in c.fetchall():
+    p = P.get(s(cod))
+    if not p: continue
+    if s(ncm) != p["NCM"]:
+        inconsistent += 1
+    else:
+        consistent["items"] += 1
+        for f, iv in (("CFOP", s(cfop)), ("CST", s(cst)), ("CSOSN", s(csosn)), ("CEST", s(cest)), ("PIS", s(pis))):
+            pv = p[f]
+            if iv is None: continue
+            eq = dg(iv) == dg(pv) if f == "CEST" else (iv.lstrip("0") == (pv or "").lstrip("0") if f == "PIS" else iv == pv)
+            agree[f]["MATCH" if eq else "MISMATCH"] += 1
+        if dg(cest):
+            hist_cest.setdefault(s(cod), Counter())[dg(cest)] += 1
+out = {"ncm_identity_consistent_items": consistent["items"], "ncm_identity_inconsistent_items": inconsistent,
+       "agreement_consistent_joins_only": {f: dict(v) for f, v in agree.items()}}
+
+# also all-time (any NCM) CEST history per product
+c.execute("select CODPRODUTO, CEST from NFCE_ITENS where CEST is not null and trim(CEST) <> ''")
+allc = {}
+for cod, cest in c.fetchall():
+    allc.setdefault(s(cod), Counter())[dg(cest)] += 1
+
+tok = [l.split("=", 1)[1].strip() for l in open(ROOT / ".env", encoding="utf-8") if l.startswith("AGENT_DEV_TOKEN=")][0]
+matrix = json.loads((ROOT / "docs" / "FISCAL_DECISION_MATRIX_V1.json").read_text(encoding="utf-8"))
+cands = [m for m in matrix["products"] if m["fields"]["CEST"]["status"] == "RULE_CANDIDATE"]
+req = urllib.request.Request("http://localhost:8000/v1/classify/batch", data=json.dumps({"products": [{"current_ncm": m["NCM"], "description": m["DESCRIPTION"] or ""} for m in cands]}).encode(),
+                             headers={"Content-Type": "application/json", "Authorization": "Bearer " + tok})
+decs = json.load(urllib.request.urlopen(req, timeout=600))["results"]
+rows = []
+for m, d in zip(cands, decs):
+    code = s(m["CODIGO"]); off = {dg(x["code"]): x for x in d["classification"].get("cest_candidates", [])}
+    h = dict(allc.get(code, {}))
+    supported = [k for k in h if k in off]
+    mva_ceps = {dg(x.get("cest")) for x in d["classification"].get("ba_st_mva_candidates", [])}
+    rows.append({"CODIGO": code, "DESCRIPTION": m["DESCRIPTION"], "NCM": m["NCM"], "official_candidates": len(off), "historical_cest": h,
+                 "historical_in_official_candidates": supported, "historical_in_ba_st_mva": [k for k in h if k in mva_ceps],
+                 "product_ncm_matches_item_ncm": None,
+                 "verdict": "CEST_HISTORICALLY_SUPPORTED" if len(h) == 1 and len(supported) == 1 else ("HISTORY_MULTIPLE_OR_UNSUPPORTED" if h else "NO_HISTORY")})
+out["cest_candidates"] = rows
+out["cest_historically_supported"] = sum(1 for r in rows if r["verdict"] == "CEST_HISTORICALLY_SUPPORTED")
+print(json.dumps(out, ensure_ascii=True, indent=1))

fiscal/scripts/analyze_inbound_observations.py

@@ -0,0 +1,82 @@
+"""Read-only extraction of populated supplier-item fiscal observations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from central.app.evidence_aggregation import Observation, aggregate_observations  # noqa: E402
+
+
+def _hash(value: object) -> str:
+    return hashlib.sha256(str(value).encode("utf-8")).hexdigest()[:16]
+
+
+def summarize_rows(rows: list[tuple[object, ...]]) -> dict:
+    observations = []
+    for product, supplier, observed_at, ncm, cfop, cst in rows:
+        identity = _hash(product)
+        supplier_id = _hash(supplier)
+        document = _hash(f"{supplier}:{product}:{observed_at}")
+        for attribute, value in (("ncm", ncm), ("cfop", cfop), ("cst", cst)):
+            if value not in (None, ""):
+                observations.append(Observation(identity, attribute, str(value).strip(), supplier_id, document, str(observed_at), "SUPPLIER_OBSERVATION"))
+    aggregate = aggregate_observations(observations)
+    return {
+        "observation_count": len(observations),
+        "aggregate_count": len(aggregate),
+        "sources": ["SUPPLIER_OBSERVATION"] if observations else [],
+        "strong_evidence_count": sum(1 for row in aggregate.values() if row["strong_evidence"]),
+        "conflict_count": sum(row["conflict_count"] for row in aggregate.values()),
+    }
+
+
+def _env() -> None:
+    path = ROOT / ".env"
+    if path.exists():
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if "=" in line and not line.lstrip().startswith("#"):
+                key, _, value = line.partition("=")
+                os.environ.setdefault(key.strip(), value.strip())
+
+
+def analyze_database(path: Path) -> dict:
+    import fdb
+
+    conn = fdb.connect(database=str(path), user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"), isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT TRIM(RDB$FIELD_NAME) FROM RDB$RELATION_FIELDS WHERE RDB$RELATION_NAME = 'C000088'")
+        fields = {row[0] for row in cur.fetchall()}
+        required = {"CODPRODUTO", "CODFORNECEDOR", "DATA", "CLASSIFICACAO_FISCAL", "CFOP", "CST"}
+        if not required <= fields:
+            return {"database": path.name, "status": "NO_COMPLETE_INBOUND_ITEM_SHAPE", "fields_available": sorted(fields)}
+        cur.execute("SELECT CODPRODUTO, CODFORNECEDOR, DATA, CLASSIFICACAO_FISCAL, CFOP, CST FROM C000088")
+        rows = cur.fetchall()
+        summary = summarize_rows(rows)
+        return {"database": path.name, "status": "ANALYZED", "items_analyzed": len(rows), **summary, "origin_field_available": False, "origin_resolution": "ORIGIN_NEEDS_EVIDENCE"}
+    finally:
+        conn.close()
+
+
+def main() -> None:
+    _env()
+    paths = [ROOT / "TESTESOFICIAIS.FDB"] + sorted((ROOT / "Banco").glob("*.FDB"))
+    result = {"artifact": "INBOUND_SUPPLIER_OBSERVATIONS_V1", "mode": "READ_ONLY", "firebird_writes": 0, "databases": []}
+    for path in paths:
+        try:
+            result["databases"].append(analyze_database(path))
+        except Exception as exc:
+            result["databases"].append({"database": path.name, "status": "UNAVAILABLE", "error_type": type(exc).__name__})
+    (ROOT / "docs/INBOUND_SUPPLIER_OBSERVATIONS_V1.json").write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"artifact": result["artifact"], "databases": len(result["databases"]), "firebird_writes": 0}))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/answer_company_context.py

@@ -0,0 +1,56 @@
+"""Review-only company questionnaire CLI; it never imports or writes Firebird."""
+import argparse
+import csv
+import json
+from pathlib import Path
+
+from central.app.ai.questionnaire import build_questionnaire, group_questions, render_csv, render_json, validate_answers
+
+
+def _load(path):
+    if Path(path).suffix.lower() == ".json":
+        return json.loads(Path(path).read_text(encoding="utf-8"))["questions"]
+    with Path(path).open(newline="", encoding="utf-8-sig") as stream:
+        return list(csv.DictReader(stream))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--questions", default="docs/LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json")
+    parser.add_argument("--answers", help="JSON object keyed by QUESTION_ID; omit for guided mode")
+    parser.add_argument("--output", default="docs/OPERATOR_CONTEXT_ANSWERS_V3.json")
+    parser.add_argument("--format", choices=("json", "csv"), default="json")
+    parser.add_argument("--confirm", action="store_true", help="write the reviewed artifact")
+    args = parser.parse_args(argv)
+    rows = _load(args.questions)
+    databases = sorted({str(q.get("DATABASE") or "").strip() for q in rows if q.get("DATABASE")})
+    existing = {q.get("DATABASE") for q in rows if q.get("KEY") == "store_ipi_profile"}
+    rows += [{"QUESTION_ID": f"QIPI-{name}", "DATABASE": name, "SCOPE": "COMPANY", "KEY": "store_ipi_profile",
+              "VALID_OPTIONS": ["POPULATE_REFERENCE_RATE", "LEAVE_NOT_APPLICABLE"],
+              "QUESTION": "Guardar a aliquota TIPI como referencia no cadastro?", "PRODUCTS_AFFECTED": 0, "CELLS": 0}
+             for name in databases if name not in existing]
+    questions = build_questionnaire([q for q in rows if str(q.get("CATEGORY", "")).upper() == "C" or q.get("KEY") == "store_ipi_profile"])
+    groups = group_questions(questions)
+    if args.answers:
+        answers = json.loads(Path(args.answers).read_text(encoding="utf-8"))
+    else:
+        answers = {}
+        for group in groups:
+            print(f"\nEMPRESA: {group['database']}\nPERGUNTA: {group['question']}\nPOR QUE PRECISA: {group['consequence']}\nPRODUTOS AFETADOS: {group['affected']['products']}\nCÉLULAS AFETADAS: {group['affected']['cells']}\nOPÇÕES: {', '.join(group['options'])}")
+            value = input("RESPOSTA (ou CANCELAR): ").strip()
+            if value.upper() == "CANCELAR":
+                print("cancelado; nada foi persistido")
+                return 0
+            for question_id in group["question_ids"]:
+                answers[question_id] = value
+    result = validate_answers(questions, answers)
+    print(json.dumps({"questions": len(questions), "groups": len(groups), "entries": len(result["entries"]), "rollback_plan": result["rollback_plan"]}, ensure_ascii=False))
+    if not args.confirm:
+        print("review only; nothing was persisted")
+        return 0
+    Path(args.output).write_text(render_csv(result) if args.format == "csv" else render_json(result), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fiscal/scripts/answer_group_questions.py

@@ -0,0 +1,42 @@
+"""Review-only group/NCM/product questionnaire CLI; it never imports context."""
+import argparse
+import json
+from pathlib import Path
+
+from central.app.ai.questionnaire import build_questionnaire, group_questions, render_csv, render_json, validate_answers
+from scripts.answer_company_context import _load
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--questions", default="docs/LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json")
+    parser.add_argument("--answers")
+    parser.add_argument("--output", default="docs/OPERATOR_GROUP_ANSWERS_V3.json")
+    parser.add_argument("--format", choices=("json", "csv"), default="json")
+    parser.add_argument("--confirm", action="store_true")
+    args = parser.parse_args(argv)
+    questions = build_questionnaire([q for q in _load(args.questions) if str(q.get("CATEGORY", "")).upper() != "C"])
+    groups = group_questions(questions)
+    if args.answers:
+        answers = json.loads(Path(args.answers).read_text(encoding="utf-8"))
+    else:
+        answers = {}
+        for group in groups:
+            print(f"\nEMPRESA: {group['database']}\nGRUPO: {group['group'] or group['scope_key']}\nPRODUTOS AFETADOS: {group['affected']['products']}\nCÉLULAS AFETADAS: {group['affected']['cells']}\nEXEMPLOS: {'; '.join(group['examples'])}\nPERGUNTA: {group['question']}\nOPÇÕES: {', '.join(group['options'])}")
+            value = input("RESPOSTA (ou CANCELAR): ").strip()
+            if value.upper() == "CANCELAR":
+                print("cancelado; nada foi persistido")
+                return 0
+            for question_id in group["question_ids"]:
+                answers[question_id] = value
+    result = validate_answers(questions, answers)
+    print(json.dumps({"questions": len(questions), "groups": len(groups), "entries": len(result["entries"])}, ensure_ascii=False))
+    if not args.confirm:
+        print("review only; nothing was persisted")
+        return 0
+    Path(args.output).write_text(render_csv(result) if args.format == "csv" else render_json(result), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fiscal/scripts/audit_company_context.py

@@ -0,0 +1,85 @@
+"""READ-ONLY company-context audit + resolver retest over every .FDB in a directory (default ./Banco).
+Writes docs/COMPANY_CONTEXT_RESOLUTION_V1.json (evidence) and docs/MULTI_DATABASE_COMPANY_CONTEXT_V1.json (outcomes).
+The full CNPJ is never written: masked value + short SHA-256 fingerprint only.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+import fdb  # noqa: E402
+from gti_fiscal_agent import company_context as cc  # noqa: E402
+
+for line in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+    if "=" in line and not line.startswith("#"):
+        k, _, v = line.partition("=")
+        os.environ.setdefault(k.strip(), v.strip())
+
+
+def evidence_for(path):
+    conn = fdb.connect(database=str(path), user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+                       isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+    try:
+        return cc.collect_evidence(conn.cursor())
+    finally:
+        conn.close()
+
+
+def table(ev):
+    rows = []
+    emissor_cnpjs = {cc.digits(e["cnpj"]) for e in ev["emissor"]}
+    docs_by_cnpj = {}
+    for d in ev["nfce_keys"]:
+        docs_by_cnpj[cc.digits(d["cnpj"])] = docs_by_cnpj.get(cc.digits(d["cnpj"]), 0) + d["n"]
+    for i, c in enumerate(ev["c000004"]):
+        cn = cc.digits(c.get("cnpj"))
+        em = next((e for e in ev["emissor"] if cc.digits(e["cnpj"]) == cn), None)
+        n_docs = docs_by_cnpj.get(cn, 0); n_fil = ev["nf_by_filial"].get(c.get("code"), 0)
+        active = bool(em) and n_docs > 0
+        rows.append({"C000004_CODE": c.get("code"), "CNPJ": cc.mask_cnpj(cn), "CNPJ_FINGERPRINT": cc.cnpj_fingerprint(cn), "UF_C000004": c.get("uf"), "CRT_C000004": c.get("crt"), "OPTANTE_SIMPLES": c.get("optante"),
+                     "EMISSOR_ID": (ev["emissor"].index(em) + 1) if em else None, "UF_EMISSOR": em.get("uf") if em else None, "CRT_EMISSOR": em.get("crt") if em else None,
+                     "DOCUMENT_COUNT": {"nfce_keys_with_this_cnpj": n_docs, "nf_C000061_with_this_CODFILIAL": n_fil}, "IS_ACTIVE_CANDIDATE": active,
+                     "EVIDENCE": [x for x in (("EMISSOR.EMITENTE_CNPJ equals this CNPJ" if em else "no EMISSOR row with this CNPJ"), (f"{n_docs} emitted NFC-e keys carry this CNPJ" if n_docs else "no emitted NFC-e key carries this CNPJ"),
+                                              (f"{n_fil} NF-e rows use CODFILIAL={c.get('code')}" if n_fil else None)) if x]})
+    return rows
+
+
+def main():
+    directory = Path(sys.argv[1]) if len(sys.argv) > 1 else ROOT / "Banco"
+    evid, outcomes = {}, {}
+    for p in sorted(directory.glob("*.FDB")):
+        ev = evidence_for(p)
+        rows = table(ev)
+        no_cfg = cc.resolve(ev, {})
+        crt_cfg = cc.resolve(ev, {"crt_source": "EMISSOR"})
+        multi = len(ev["c000004"]) > 1
+        neg = {}
+        if multi:  # negative tests on real data: wrong company / unknown CNPJ must not resolve silently
+            other = next((c for c in ev["c000004"] if not next((e for e in ev["emissor"] if cc.digits(e["cnpj"]) == cc.digits(c["cnpj"])), None)), None)
+            neg["configured_non_emitting_company"] = cc.resolve(ev, {"company_code": other["code"], "crt_source": "EMISSOR"})["classification"] if other else None
+            neg["configured_unknown_cnpj"] = cc.resolve(ev, {"company_cnpj": "00000000000000"})["classification"]
+        crt_authority = {"EMISSOR_values": sorted({e.get("crt") for e in ev["emissor"] if e.get("crt")}), "C000004_selected_row": no_cfg.get("crt_candidates") or {"C000004": no_cfg.get("company_crt")}}
+        evid[p.stem] = {"c000004_rows": len(ev["c000004"]), "emissor_rows": len(ev["emissor"]), "companies": rows, "nfce_key_groups": [{"cUF": d["cuf"], "cnpj": cc.mask_cnpj(d["cnpj"]), "model": "65", "n": d["n"]} for d in ev["nfce_keys"]],
+                        "nf_by_filial": ev["nf_by_filial"]}
+        outcomes[p.stem] = {"without_config": cc.preflight_report(no_cfg), "with_COMPANY_CRT_SOURCE=EMISSOR": cc.preflight_report(crt_cfg), "negative_tests": neg,
+                            "crt_source_status": no_cfg.get("crt_status") or ("CRT_SOURCE_CONFLICT" if "CRT_SOURCE_CONFLICT" in " ".join(no_cfg["reasons"]) else "CRT_SOURCE_UNKNOWN"),
+                            "uf_source_status": no_cfg.get("uf_status") or "UF_SOURCE_UNKNOWN", "resolution_class": no_cfg["classification"]}
+    classes = {}
+    for k, v in outcomes.items():
+        classes.setdefault(v["resolution_class"], []).append(k)
+    authority = {
+        "CRT": {"emission_authority": "EMISSOR.EMITENTE_CRT", "evidence": ["GtiVendas_NFCe.exe (NFC-e) and Envio NF-e.exe (NF-e) bind QrEmissor.EMITENTE_CRT/EMITENTE_UF/EMITENTE_CNPJ and never reference C000004.CRT or OPTANTE_SIMPLES",
+                                                                                  "SGV_5.0.6.124.exe (ERP) binds C000004.CRT (qrFilialCRT/QrSPEDFilialCRT) and OPTANTE_SIMPLES for the filial registry/SPED and has no EMITENTE_* binding",
+                                                                                  "emitted XML is not stored in the database (C000061.NFE_XML and XML_MES.XML hold file paths), so the CRT tag of issued documents could not be read directly"],
+                "status": "CRT_SOURCE_CONFLICT where the two values differ; the resolver refuses to choose without COMPANY_CRT_SOURCE"},
+        "UF": {"status": "UF_SOURCE_CONFIRMED", "evidence": "EMISSOR.EMITENTE_UF, C000004.UF and the cUF of 100% of emitted NFC-e keys agree in all 4 databases"},
+        "COMPANY": {"status": "confirmed", "evidence": "EMISSOR.EMITENTE_CNPJ equals exactly one C000004 CNPJ in every database and 100% of emitted NFC-e keys carry that CNPJ; other C000004 rows (RINCAO) have no documents"}}
+    (ROOT / "docs" / "COMPANY_CONTEXT_RESOLUTION_V1.json").write_text(json.dumps({"artifact": "COMPANY_CONTEXT_RESOLUTION_V1", "firebird_writes": 0, "authority": authority, "databases": evid}, ensure_ascii=False, indent=1), encoding="utf-8")
+    (ROOT / "docs" / "MULTI_DATABASE_COMPANY_CONTEXT_V1.json").write_text(json.dumps({"artifact": "MULTI_DATABASE_COMPANY_CONTEXT_V1", "firebird_writes": 0, "resolution_classes": classes, "databases": outcomes}, ensure_ascii=False, indent=1), encoding="utf-8")
+    print(json.dumps({k: (v["resolution_class"], v["with_COMPANY_CRT_SOURCE=EMISSOR"]["COMPANY_CONTEXT"], v["with_COMPANY_CRT_SOURCE=EMISSOR"]["company_crt"], v["negative_tests"]) for k, v in outcomes.items()}, ensure_ascii=False))
+    print(classes)
+
+
+main()

fiscal/scripts/audit_erp_fields.py

@@ -0,0 +1,40 @@
+"""Read-only audit of fiscal-field semantics in C000025 (types, value distributions, comments)."""
+import json, os, sys
+from collections import Counter
+from pathlib import Path
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+from gti_fiscal_agent.firebird_reader import _connect  # noqa: E402
+
+FIELDS = ["CLASSIFICACAO_FISCAL","NCM","IPI","EX_TIPI","CEST","CFOP_ENTRADA","CFOP","CST_ENTRADA","CST","ALIQUOTA","CSOSN",
+          "COD_ENTRADA_PIS","COD_SAIDA_PIS","ALIQ_PIS","COD_ENTRADA_COFINS","COD_SAIDA_COFINS","ALIQ_COFINS","CST_IPI","ORIGEM","IAT","INCIDENCIA_PISCOFINS","IPPT"]
+
+def load_env():
+    for line in (ROOT/".env").read_text(encoding="utf-8").splitlines():
+        if "=" in line and not line.startswith("#"):
+            k, _, v = line.partition("="); os.environ.setdefault(k.strip(), v.strip())
+
+def main():
+    load_env()
+    conn = _connect(os.environ); cur = conn.cursor()
+    cur.execute("""SELECT rf.RDB$FIELD_NAME, f.RDB$FIELD_TYPE, f.RDB$FIELD_LENGTH, f.RDB$FIELD_PRECISION, f.RDB$FIELD_SCALE, f.RDB$CHARACTER_LENGTH, rf.RDB$DESCRIPTION, rf.RDB$DEFAULT_SOURCE
+                   FROM RDB$RELATION_FIELDS rf JOIN RDB$FIELDS f ON rf.RDB$FIELD_SOURCE=f.RDB$FIELD_NAME WHERE rf.RDB$RELATION_NAME='C000025'""")
+    meta = {}
+    for r in cur.fetchall():
+        name = r[0].strip()
+        if name in FIELDS:
+            meta[name] = {"type_code": r[1], "len": r[5] or r[2], "precision": r[3], "scale": r[4], "comment": str(r[6]) if r[6] else None, "default": str(r[7]) if r[7] else None}
+    out = {}
+    for f in FIELDS:
+        if f not in meta:
+            out[f] = {"exists": False}; continue
+        cur.execute(f"SELECT {f}, COUNT(*) FROM C000025 GROUP BY {f}")
+        rows = sorted(((str(v).strip() if v is not None else None, c) for v, c in cur.fetchall()), key=lambda x: -x[1])
+        out[f] = {"exists": True, **meta[f], "distinct": len(rows), "top": rows[:12]}
+    # relations that may hold context (company/tax config), names only
+    cur.execute("SELECT RDB$RELATION_NAME FROM RDB$RELATIONS WHERE RDB$SYSTEM_FLAG=0 AND (RDB$RELATION_NAME LIKE '%EMPRESA%' OR RDB$RELATION_NAME LIKE '%CFOP%' OR RDB$RELATION_NAME LIKE '%TRIB%' OR RDB$RELATION_NAME LIKE '%ICMS%' OR RDB$RELATION_NAME LIKE '%CST%' OR RDB$RELATION_NAME LIKE '%NATUREZA%')")
+    out["_related_tables"] = [r[0].strip() for r in cur.fetchall()]
+    conn.close()
+    print(json.dumps(out, ensure_ascii=False, indent=1, default=str))
+
+main()

fiscal/scripts/audit_firebird_database.py

@@ -0,0 +1,129 @@
+"""READ-ONLY audit of any SGV Firebird database (restaurante / mercado / oficina ...).
+
+    python audit_firebird_database.py <FDB> [--json out.json]
+
+Credentials come from the process environment (FB_USER / FB_PASSWORD, optional FIREBIRD_CLIENT_LIBRARY) or the
+local ignored .env — never from the command line, never printed. The connection uses read-only isolation and the
+script executes SELECT statements only. It never enables writes for the audited database.
+"""
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src")); sys.path.insert(0, str(ROOT / "src"))
+
+FISCAL_FIELDS = ["CLASSIFICACAO_FISCAL", "NCM", "CFOP", "CFOP_ENTRADA", "CST", "CST_ENTRADA", "ALIQUOTA", "CEST", "CSOSN", "IPI", "EX_TIPI", "CST_IPI",
+                 "COD_ENTRADA_PIS", "COD_SAIDA_PIS", "ALIQ_PIS", "COD_ENTRADA_COFINS", "COD_SAIDA_COFINS", "ALIQ_COFINS", "ORIGEM", "COD_ORIGEM_MERCADORIA",
+                 "IAT", "INCIDENCIA_PISCOFINS", "IPPT", "GRUPO_ICMS", "SITUACAO_TRIBUTARIA", "MARGEM_AGREGADA"]
+# Firebird RDB$FIELD_TYPE -> family
+_FAMILY = {7: "int", 8: "int", 16: "int", 10: "float", 11: "float", 27: "float", 12: "date", 13: "time", 35: "timestamp", 14: "text", 37: "text", 261: "blob"}
+# expected type family per field (from docs/ERP_FISCAL_FIELD_MAP_V1.json); text fields may also be char
+EXPECTED_FAMILY = {"CLASSIFICACAO_FISCAL": "text", "NCM": "text", "CFOP": "text", "CFOP_ENTRADA": ("text", "int"), "CST": "text", "CST_ENTRADA": ("text", "int"), "ALIQUOTA": ("float", "int"),
+                   "CEST": "text", "CSOSN": "text", "IPI": ("float", "int"), "EX_TIPI": "text", "CST_IPI": ("text", "int"), "COD_ENTRADA_PIS": "text", "COD_SAIDA_PIS": "text",
+                   "ALIQ_PIS": "text", "COD_ENTRADA_COFINS": "text", "COD_SAIDA_COFINS": "text", "ALIQ_COFINS": "text", "ORIGEM": "text", "COD_ORIGEM_MERCADORIA": "int",
+                   "IAT": "text", "INCIDENCIA_PISCOFINS": "text", "IPPT": "text", "GRUPO_ICMS": "text", "SITUACAO_TRIBUTARIA": "text", "MARGEM_AGREGADA": ("float", "int")}
+
+
+def type_family(code):
+    return _FAMILY.get(code, f"other:{code}")
+
+
+def ncm_bucket(value):
+    v = "" if value is None else str(value).strip()
+    if not v:
+        return "blank"
+    return "eight_digits" if re.fullmatch(r"\d{8}", v) else "other_format"
+
+
+def compat(columns):
+    """columns: {FIELD: type_code}. Returns per-field compatibility against the expected families."""
+    out = {}
+    for f, exp in EXPECTED_FAMILY.items():
+        if f not in columns:
+            out[f] = "MISSING"
+            continue
+        fam = type_family(columns[f]); exp = (exp,) if isinstance(exp, str) else exp
+        out[f] = "OK" if fam in exp else f"TYPE_DIFFERS({fam} not in {'/'.join(exp)})"
+    return out
+
+
+def load_env():
+    env_file = ROOT / ".env"
+    if env_file.exists():
+        for line in env_file.read_text(encoding="utf-8").splitlines():
+            if "=" in line and not line.startswith("#"):
+                k, _, v = line.partition("="); os.environ.setdefault(k.strip(), v.strip())
+
+
+def audit(path, env):
+    import fdb
+    from gti_discovery.fingerprint import build_fingerprint
+    from gti_fiscal_agent.firebird_reader import parse_company_context
+    conn = fdb.connect(database=path, user=env["FB_USER"], password=env["FB_PASSWORD"], fb_library_name=env.get("FIREBIRD_CLIENT_LIBRARY"),
+                       isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+    try:
+        cur = conn.cursor()
+        res = {"database": Path(path).name, "mode": "READ_ONLY", "firebird_server_version": getattr(conn, "server_version", None), "ods": f"{getattr(conn, 'ods_version', '?')}.{getattr(conn, 'ods_minor_version', '?')}"}
+        cur.execute("""SELECT TRIM(rf.RDB$RELATION_NAME), TRIM(rf.RDB$FIELD_NAME), f.RDB$FIELD_TYPE, COALESCE(f.RDB$CHARACTER_LENGTH, f.RDB$FIELD_LENGTH), f.RDB$FIELD_SCALE
+                       FROM RDB$RELATION_FIELDS rf JOIN RDB$FIELDS f ON f.RDB$FIELD_NAME = rf.RDB$FIELD_SOURCE
+                       JOIN RDB$RELATIONS r ON r.RDB$RELATION_NAME = rf.RDB$RELATION_NAME WHERE COALESCE(r.RDB$SYSTEM_FLAG, 0) = 0""")
+        meta = {}
+        for t, c, ty, ln, sc in cur.fetchall():
+            meta.setdefault(t, []).append({"name": c, "type": ty, "length": ln, "scale": sc})
+        res["schema_fingerprint"] = build_fingerprint({"tables": [{"name": t, "columns": cols} for t, cols in sorted(meta.items())]})
+        res["tables"] = len(meta)
+        # company context
+        if "C000004" in meta:
+            try:
+                cur.execute("SELECT UF, CRT FROM C000004"); res["company"] = {"status": "OK", **parse_company_context(cur.fetchall())}
+            except ValueError as e:
+                res["company"] = {"status": "UNAVAILABLE", "error": str(e)}
+        else:
+            res["company"] = {"status": "C000004_ABSENT"}
+        # products
+        res["C000025_present"] = "C000025" in meta
+        if res["C000025_present"]:
+            cols = {c["name"]: c["type"] for c in meta["C000025"]}
+            res["field_mapping_compatibility"] = compat(cols)
+            res["field_mapping_compatibility_summary"] = {k: sum(1 for v in res["field_mapping_compatibility"].values() if (v == k or v.startswith(k))) for k in ("OK", "MISSING", "TYPE_DIFFERS")}
+            cur.execute("SELECT COUNT(*) FROM C000025"); res["product_count"] = cur.fetchone()[0]
+            ncm_col = "CLASSIFICACAO_FISCAL" if "CLASSIFICACAO_FISCAL" in cols else None
+            if ncm_col:
+                cur.execute(f"SELECT {ncm_col}, COUNT(*) FROM C000025 GROUP BY {ncm_col}")
+                b = {"eight_digits": 0, "blank": 0, "other_format": 0}
+                for v, n in cur.fetchall():
+                    b[ncm_bucket(v)] += n
+                res["ncm_coverage"] = {**b, "share_eight_digits": round(b["eight_digits"] / res["product_count"], 4) if res["product_count"] else None}
+            pop = {}
+            for f in FISCAL_FIELDS:
+                if f in cols:
+                    cur.execute(f"SELECT COUNT(*) FROM C000025 WHERE {f} IS NOT NULL AND TRIM(CAST({f} AS VARCHAR(60))) <> ''")
+                    pop[f] = cur.fetchone()[0]
+            res["fiscal_field_population"] = pop
+        return res
+    finally:
+        conn.close()
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("fdb"); ap.add_argument("--json")
+    a = ap.parse_args(argv)
+    load_env()
+    if not os.environ.get("FB_USER") or not os.environ.get("FB_PASSWORD"):
+        raise SystemExit("FB_USER/FB_PASSWORD must be set in the environment (never on the command line)")
+    if not Path(a.fdb).is_file():
+        raise SystemExit(f"database file not found: {a.fdb}")
+    res = audit(a.fdb, os.environ)
+    text = json.dumps(res, ensure_ascii=False, indent=1, default=str)
+    if a.json:
+        Path(a.json).write_text(text, encoding="utf-8")
+    print(text)
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/audit_local_writes.py

@@ -0,0 +1,68 @@
+"""Semantic audit of the local-completion writes (Local Completion V2). Offline: reads docs/runs/local_completion/* only.
+Verdicts: SEMANTICALLY_PROVEN | NEEDS_REVIEW | INVALID_RULE. Emits docs/LOCAL_WRITE_SEMANTIC_AUDIT_V2.json (+ per-field tables) and rollback_plan.json {db: {field: [codes]}} for every write that is not PROVEN."""
+import csv, gzip, json, pickle, re, sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]; ST = ROOT / "docs" / "runs" / "local_completion"
+DBS = ["CONSTRUCAO", "MMMODAS", "RINCAO", "UNIAO", "TESTESOFICIAIS"]
+tipi = defaultdict(dict)
+for line in (ST / "tipi_export.txt").read_text(encoding="utf-8").splitlines():
+    ncm, ex, rate, txt = line.split("|"); tipi[ncm][ex] = (float(rate) if rate else None, txt)
+st_prefixes = {re.sub(r"\D", "", x) for x in (ST / "ba_st_ncm_export.txt").read_text(encoding="utf-8").split()}
+ST_CODES = {"010", "030", "070", "060", "201", "202", "203", "500", "10", "30", "70", "60"}
+audit = defaultdict(list); plan = defaultdict(lambda: defaultdict(list)); table = []
+for n in DBS:
+    b = pickle.load(gzip.open(ST / f"{n}_before.pkl.gz", "rb")); cols = b["columns"]; rows = b["rows"]; g = lambda code, c: rows[code][cols.index(c)]  # noqa: E731
+    dry = {}
+    for l in gzip.open(ST / f"{n}_dryrun.ndjson.gz", "rt", encoding="utf-8"):
+        r = json.loads(l); dry[(r["codigo"], r["field"])] = r
+    for l in gzip.open(ST / f"{n}_write_audit.ndjson.gz", "rt", encoding="utf-8"):
+        a = json.loads(l); code = a["product_code"]
+        for f, v in a["fields"].items():
+            d = dry[(code, f)]; ncm = re.sub(r"\D", "", str(g(code, "CLASSIFICACAO_FISCAL") or "")); rule = d["reason"]; ev = ""; verdict = "SEMANTICALLY_PROVEN"
+            if f == "COD_ORIGEM_MERCADORIA":
+                verdict, ev = "INVALID_RULE", f"CST digit is padding: CST={g(code,'CST')!r} while declared-origin products (1/2) also carry CST digit 0"
+            elif f == "IPI":
+                ncm_ok = dry[(code, "CLASSIFICACAO_FISCAL")]["status"] == "ALREADY_CORRECT" and len(ncm) == 8
+                base = tipi.get(ncm, {}).get("")
+                ex_prod = str(g(code, "EX_TIPI") or "").strip()
+                if not ncm_ok or base is None or base[0] is None or abs(base[0] - float(v["after"])) > 1e-9:
+                    verdict, ev = "INVALID_RULE", "TIPI numeric base rate does not match"
+                elif g(code, "IPI") is not None:
+                    verdict, ev = "NEEDS_REVIEW", "overwrote a non-null IPI"
+                elif ex_prod:
+                    verdict, ev = "NEEDS_REVIEW", f"product declares EX_TIPI={ex_prod}"
+                else:
+                    ev = f"NCM {ncm} valid; TIPI base row rate={base[0]} (text {base[1]!r}); EX rows for NCM: {sorted(k for k in tipi[ncm] if k)}; before NULL"
+            elif f == "CFOP":
+                cst, csosn = str(g(code, "CST") or "").strip(), str(g(code, "CSOSN") or "").strip()
+                st_decl = csosn in {"500", "201", "202", "203"} or cst in {"060", "010", "070", "030"}
+                if d["reason"] == "PROVEN_ROLE_AND_ST_CONTRADICT_DECLARED_CFOP" and v["before"] == "5405" and v["after"] == "5102":
+                    verdict, ev = ("INVALID_RULE", f"ERP declares ICMS-ST already retained (CST={cst}, CSOSN={csosn}); CFOP 5102 contradicts the product's own CST/CSOSN, official table alone cannot override it") if st_decl else ("NEEDS_REVIEW", "ST not declared")
+                elif v["after"] == "5101":
+                    ipp = dry.get((code, "IPPT"), {}).get("reason", "")
+                    strong = "COMPOSICAO" in ipp or "RECEITA_INGREDIENTES" in ipp
+                    verdict, ev = ("SEMANTICALLY_PROVEN", f"own production evidence: {ipp}") if strong else ("NEEDS_REVIEW", f"only kitchen-routing flag: {ipp}")
+                elif v["after"] == "5102" and v["before"] is None:
+                    in_st = any(ncm.startswith(p) for p in st_prefixes if len(p) in (4, 6, 8))
+                    verdict, ev = ("SEMANTICALLY_PROVEN", f"resale; CST={cst} CSOSN={csosn} not ST; NCM {ncm} not in BA ST prefixes") if (not st_decl and not in_st) else ("NEEDS_REVIEW", "possible ST")
+            elif f == "CEST":
+                cest = str(v["after"]); fmt = f"{cest[:2]}.{cest[2:5]}.{cest[5:]}"
+                verdict, ev = "SEMANTICALLY_PROVEN", f"official CEST dataset: NCM {ncm} linked exactly to {fmt} (single candidate); before blank"
+            elif f == "IPPT":
+                strong = "COMPOSICAO" in rule or "RECEITA_INGREDIENTES" in rule
+                verdict, ev = ("SEMANTICALLY_PROVEN", f"ERP evidence: {rule}") if strong else ("NEEDS_REVIEW", f"only kitchen-routing flag: {rule}")
+            else:
+                verdict, ev = "NEEDS_REVIEW", "no audit rule"
+            audit[(n, f)].append(verdict)
+            if verdict != "SEMANTICALLY_PROVEN":
+                plan[n][f].append(code)
+            if f in ("CFOP", "CEST", "IPPT"):
+                table.append({"database": n, "product": code, "field": f, "before": v["before"], "after": v["after"], "rule": rule, "evidence": ev, "verdict": verdict})
+summary = {f"{n}|{f}": dict(Counter(v)) for (n, f), v in audit.items()}
+(ROOT / "docs" / "LOCAL_WRITE_SEMANTIC_AUDIT_V2.json").write_text(json.dumps({"summary": summary, "small_field_writes": table}, ensure_ascii=False, indent=1), encoding="utf-8")
+with open(ROOT / "docs" / "LOCAL_WRITE_SEMANTIC_AUDIT_V2_CFOP_CEST_IPPT.csv", "w", newline="", encoding="utf-8") as fh:
+    w = csv.DictWriter(fh, fieldnames=list(table[0])); w.writeheader(); w.writerows(table)
+(ST / "rollback_plan.json").write_text(json.dumps(plan), encoding="utf-8")
+for k, v in summary.items(): print(k, v)

fiscal/scripts/audit_multi_databases.py

@@ -0,0 +1,154 @@
+"""READ-ONLY schema/capability/population audit of every .FDB in a directory (default: ./Banco).
+
+    python scripts/audit_multi_databases.py [DIR]
+
+Uses read-only isolation and SELECT only; credentials from FB_USER/FB_PASSWORD (env or local ignored .env).
+Writes docs/runs/multi_db/<DB>.json (raw) and docs/MULTI_DATABASE_SCHEMA_AUDIT_V1.json,
+docs/MULTI_DATABASE_FIELD_COMPATIBILITY_V1.json. Never modifies a database.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src")); sys.path.insert(0, str(ROOT / "src"))
+import sgv_capabilities as cap  # noqa: E402
+
+REFERENCE = json.loads((ROOT / "docs" / "runs" / "audit_TESTESOFICIAIS.json").read_text(encoding="utf-8"))["schema_fingerprint"]
+SIGNAL_TABLES = ["MESAS", "R000002", "RECEITA_INGREDIENTES", "DELIVERY_M", "C000051", "NFCE", "NFCE_ITENS", "C000032", "C000062", "C000088", "C000100", "C000030", "C000061"]
+CONTEXT_TABLES = ["C000030", "C000032", "C000062", "C000088", "C000100", "NFCE_ITENS", "RECEITA_INGREDIENTES"]
+
+
+def load_env():
+    f = ROOT / ".env"
+    if f.exists():
+        for line in f.read_text(encoding="utf-8").splitlines():
+            if "=" in line and not line.startswith("#"):
+                k, _, v = line.partition("=")
+                os.environ.setdefault(k.strip(), v.strip())
+
+
+def audit_one(path):
+    import fdb
+    from gti_discovery.fingerprint import build_fingerprint
+    from gti_fiscal_agent.firebird_reader import parse_company_context
+    conn = fdb.connect(database=str(path), user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+                       isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+    try:
+        cur = conn.cursor()
+        res = {"file": path.name, "size_mb": round(path.stat().st_size / 1e6, 1), "mode": "READ_ONLY", "firebird_server_version": getattr(conn, "server_version", None),
+               "ods": f"{getattr(conn, 'ods_version', '?')}.{getattr(conn, 'ods_minor_version', '?')}"}
+        cur.execute("""SELECT TRIM(rf.RDB$RELATION_NAME), TRIM(rf.RDB$FIELD_NAME), f.RDB$FIELD_TYPE, COALESCE(f.RDB$CHARACTER_LENGTH, f.RDB$FIELD_LENGTH), f.RDB$FIELD_SCALE
+                       FROM RDB$RELATION_FIELDS rf JOIN RDB$FIELDS f ON f.RDB$FIELD_NAME = rf.RDB$FIELD_SOURCE JOIN RDB$RELATIONS r ON r.RDB$RELATION_NAME = rf.RDB$RELATION_NAME
+                       WHERE COALESCE(r.RDB$SYSTEM_FLAG, 0) = 0""")
+        meta = {}
+        for t, c, ty, ln, sc in cur.fetchall():
+            meta.setdefault(t, []).append({"name": c, "type": ty, "length": ln, "scale": sc})
+        res["tables"] = len(meta)
+        res["schema_fingerprint"] = build_fingerprint({"tables": [{"name": t, "columns": cols} for t, cols in sorted(meta.items())]})
+        res["C000004_present"] = "C000004" in meta; res["C000025_present"] = "C000025" in meta
+        company = {"status": "C000004_ABSENT"}
+        if res["C000004_present"]:
+            names = {c["name"] for c in meta["C000004"]}
+            try:
+                cur.execute("SELECT UF, CRT FROM C000004"); company = {"status": "OK", **parse_company_context(cur.fetchall())}
+            except ValueError as e:
+                company = {"status": "UNAVAILABLE", "error": str(e)}
+            for col in ("OPTANTE_SIMPLES", "OPTANTE_SUPER_SIMPLES", "SUBSTITUTO_TRIBUTARIO", "CONTRIBUINTE_IPI", "ICMS_CSOSN"):
+                if col in names:
+                    cur.execute(f"SELECT FIRST 1 {col} FROM C000004"); row = cur.fetchone(); company[col] = None if row is None or row[0] is None else str(row[0]).strip()
+            for col in ("FANTASIA", "NOME_FANTASIA", "RAZAO_SOCIAL", "EMPRESA", "NOME"):  # short display name only, never CNPJ
+                if col in names:
+                    cur.execute(f"SELECT FIRST 1 {col} FROM C000004"); row = cur.fetchone(); company["name"] = None if row is None or row[0] is None else str(row[0]).strip()[:40]; break
+            cur.execute("SELECT CODIGO, UF, CRT FROM C000004")
+            rows = [[None if v is None else str(v).strip() for v in r] for r in cur.fetchall()]
+            company["rows"] = len(rows); company["rows_summary"] = rows
+            if "FILIAL" in names:
+                cur.execute("SELECT FIRST 1 FILIAL FROM C000004 ORDER BY CODIGO"); r0 = cur.fetchone()
+                company["filial_name_first_row"] = None if r0 is None or r0[0] is None else str(r0[0]).strip()[:50]
+        if "EMISSOR" in meta and any(c["name"] == "EMITENTE_CRT" for c in meta["EMISSOR"]):
+            cur.execute("SELECT EMITENTE_CRT FROM EMISSOR"); company["emissor_crt"] = sorted({str(r[0]).strip() for r in cur.fetchall() if r[0] is not None})
+        res["company"] = company
+        counts = {}
+        for t in SIGNAL_TABLES:
+            if t in meta:
+                cur.execute(f'SELECT COUNT(*) FROM "{t}"'); counts[t] = cur.fetchone()[0]
+            else:
+                counts[t] = None
+        res["table_rows"] = counts
+        if res["C000025_present"]:
+            cols = {c["name"]: c["type"] for c in meta["C000025"]}
+            res["C000025_columns"] = len(cols)
+            full = {c["name"]: c for c in meta["C000025"]}
+            res["field_types"] = {f: [full[f]["type"], full[f]["length"], full[f]["scale"]] for f in cap.WRITE_TARGETS + [cap.ORIGIN_FIELD] if f in full}
+            res["capabilities"] = cap.detect_capabilities(cols)
+            res["field_compatibility"] = cap.field_compatibility(cols)
+            cur.execute("SELECT COUNT(*) FROM C000025"); res["product_count"] = cur.fetchone()[0]
+            dist, pop = {}, {}
+            for f in cap.WRITE_TARGETS + [cap.ORIGIN_FIELD]:
+                if f in cols:
+                    cur.execute(f'SELECT "{f}", COUNT(*) FROM C000025 GROUP BY "{f}" ORDER BY 2 DESC')
+                    rows = [(None if v is None else str(v).strip(), n) for v, n in cur.fetchall()]
+                    pop[f] = sum(n for v, n in rows if v not in (None, ""))
+                    dist[f] = {"distinct": len(rows), "top": rows[:8]}
+            res["fiscal_field_population"] = pop; res["fiscal_field_distribution"] = dist
+            for extra, sql in (("kitchen_products", "SELECT COUNT(*) FROM C000025 WHERE PROD_COZINHA = 1"), ("vehicle_products", "SELECT COUNT(*) FROM C000025 WHERE VEIC_TIPO IS NOT NULL AND TRIM(VEIC_TIPO) <> ''")):
+                col = "PROD_COZINHA" if "COZINHA" in sql else "VEIC_TIPO"
+                if col in cols:
+                    cur.execute(sql); res[extra] = cur.fetchone()[0]
+            grade = [t for t in meta if "GRADE" in t]
+            res["grade_tables"] = {t: None for t in grade}
+            gi = 0
+            for t in grade:
+                cur.execute(f'SELECT COUNT(*) FROM "{t}"'); n = cur.fetchone()[0]; res["grade_tables"][t] = n; gi += n
+            sig = {"restaurant_tables_rows": (counts.get("MESAS") or 0) + (counts.get("R000002") or 0), "kitchen_products": res.get("kitchen_products", 0), "recipes": counts.get("RECEITA_INGREDIENTES") or 0,
+                   "service_orders": counts.get("C000051") or 0, "vehicle_products": res.get("vehicle_products", 0), "grade_items": gi, "nfce_items": counts.get("NFCE_ITENS") or 0}
+            seg, score, ev = cap.infer_segment(sig, " ".join(str(company.get(k) or "") for k in ("name", "filial_name_first_row")))
+            res["segment_inferred"] = {"segment": seg, "score": score, "evidence": ev, "signals": sig, "note": "inferred from table population, not from the file name"}
+        return res
+    finally:
+        conn.close()
+
+
+def main():
+    load_env()
+    directory = Path(sys.argv[1]) if len(sys.argv) > 1 else ROOT / "Banco"
+    dbs = sorted(directory.glob("*.FDB")) + sorted(p for p in directory.glob("*.fdb") if p.suffix != ".FDB")
+    out_dir = ROOT / "docs" / "runs" / "multi_db"; out_dir.mkdir(parents=True, exist_ok=True)
+    audits = []
+    ref_types = audit_one(ROOT / "TESTESOFICIAIS.FDB").get("field_types", {})  # reference database, read-only
+    for p in dbs:
+        try:
+            a = audit_one(p)
+            a["type_variations_vs_reference"] = {f: {"reference": ref_types.get(f), "this": v} for f, v in a.get("field_types", {}).items() if ref_types.get(f) != v}
+            a["schema_class"] = cap.classify_schema(a["C000004_present"], a["C000025_present"], a["schema_fingerprint"], REFERENCE, a.get("field_compatibility", {}))
+        except Exception as e:  # noqa: BLE001 — record, never guess
+            a = {"file": p.name, "size_mb": round(p.stat().st_size / 1e6, 1), "error": f"{type(e).__name__}: {str(e)[:200]}", "schema_class": "INCOMPATIBLE"}
+        (out_dir / f"{p.stem}.json").write_text(json.dumps(a, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+        audits.append(a)
+        print(p.name, a.get("schema_class"), a.get("product_count"), a.get("company"), a.get("error", ""))
+    ok = [a for a in audits if "error" not in a]
+    schema_doc = {"artifact": "MULTI_DATABASE_SCHEMA_AUDIT_V1", "firebird_writes": 0, "directory": directory.name, "reference_fingerprint_TESTESOFICIAIS": REFERENCE, "databases_found": len(dbs), "databases_audited": len(ok),
+                  "classification_counts": {k: sum(1 for a in audits if a["schema_class"] == k) for k in ("REFERENCE_SCHEMA_MATCH", "COMPATIBLE_WITH_VARIATIONS", "INCOMPATIBLE")},
+                  "databases": [{k: a.get(k) for k in ("file", "size_mb", "firebird_server_version", "ods", "schema_fingerprint", "tables", "product_count", "company", "C000004_present", "C000025_present", "schema_class",
+                                                        "capabilities", "segment_inferred", "table_rows", "error")} for a in audits]}
+    (ROOT / "docs" / "MULTI_DATABASE_SCHEMA_AUDIT_V1.json").write_text(json.dumps(schema_doc, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    fc = {}
+    for f in cap.WRITE_TARGETS + [cap.ORIGIN_FIELD]:
+        fc[f] = {"status_per_db": {a["file"]: a.get("field_compatibility", {}).get(f, "N/A") for a in audits},
+                 "population_per_db": {a["file"]: a.get("fiscal_field_population", {}).get(f) for a in ok},
+                 "distribution_top_per_db": {a["file"]: a.get("fiscal_field_distribution", {}).get(f, {}).get("top", [])[:5] for a in ok}}
+    all_present = [f for f in cap.WRITE_TARGETS if all(a.get("field_compatibility", {}).get(f) in ("PRESENT_OK", "PRESENT_TYPE_VARIATION") for a in ok)]
+    variations = {}
+    for a in ok:
+        for f, v in a.get("type_variations_vs_reference", {}).items():
+            variations.setdefault(f, {})[a["file"]] = v
+        for f, v in a.get("field_compatibility", {}).items():
+            if v not in ("PRESENT_OK",):
+                variations.setdefault(f, {})[a["file"]] = v
+    (ROOT / "docs" / "MULTI_DATABASE_FIELD_COMPATIBILITY_V1.json").write_text(json.dumps({"artifact": "MULTI_DATABASE_FIELD_COMPATIBILITY_V1", "write_targets_present_in_all": all_present, "write_targets_count": len(cap.WRITE_TARGETS),
+                                                                                       "variations": variations, "fields": fc}, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+
+
+main()

fiscal/scripts/ba_anexo1_refresh_diff.py

@@ -0,0 +1,30 @@
+"""Compare the ACTIVE BA_ST_MVA source PDF with a freshly downloaded RICMS-BA Anexo 1 and list the affected products. Read-only; changes no dataset."""
+import gzip, json, pickle, re, sys
+from pathlib import Path
+from pypdf import PdfReader
+ROOT = Path(__file__).resolve().parents[1]; sys.path.insert(0, str(ROOT))
+from central.app.datasets.ba_st_mva import parse_page  # noqa: E402
+
+def load(p):
+    recs = []
+    for i, pg in enumerate(PdfReader(p).pages, 1):
+        f, _ = parse_page(pg.extract_text() or "", i); recs += f
+    return recs
+
+def key(r): return (r["item"], r["cest"] or "")
+old = load(ROOT / "sources/raw/bootstrap_v1/decreto_2012_13780_ricms_anexo_1_vigente_2026.pdf"); new = load(ROOT / "sources/raw/bootstrap_v1/decreto_2012_13780_ricms_anexo_1_vigente_2026_dl20260921.pdf")
+sig = lambda r: (tuple(sorted(r["ncm_sh"] or [])), r["mva_original"], r["mva_adjusted"])  # noqa: E731
+o = {key(r): r for r in old}; n = {key(r): r for r in new}
+added = sorted(set(n) - set(o)); removed = sorted(set(o) - set(n)); changed = sorted(k for k in set(o) & set(n) if sig(o[k]) != sig(n[k]))
+def prefixes(recs): return {re.sub(r"\D", "", x) for r in recs for x in (r["ncm_sh"] or []) if len(re.sub(r"\D", "", x)) in (4, 6, 8)}
+po, pn = prefixes(old), prefixes(new); gone, come = po - pn, pn - po
+affected = {}
+for name in ["CONSTRUCAO", "MMMODAS", "RINCAO", "UNIAO", "TESTESOFICIAIS"]:
+    snap = pickle.load(gzip.open(ROOT / f"docs/runs/local_completion/{name}_before.pkl.gz", "rb")); cols = snap["columns"]; i = cols.index("CLASSIFICACAO_FISCAL")
+    hit = [c for c, r in snap["rows"].items() if any(re.sub(r"\D", "", r[i] or "").startswith(p) for p in (gone | come))]
+    affected[name] = {"products": len(hit), "examples": hit[:5]}
+doc = {"old_records": len(old), "new_records": len(new), "items_added": [list(k) for k in added], "items_removed": [list(k) for k in removed], "items_changed": [{"key": list(k), "old": sig(o[k]), "new": sig(n[k])} for k in changed[:60]], "items_changed_count": len(changed),
+       "ncm_prefixes_no_longer_listed": sorted(gone)[:100], "ncm_prefixes_newly_listed": sorted(come)[:100], "affected_products_by_database": affected,
+       "note": "No dataset was modified; the Hub still serves the ACTIVE BA_ST_MVA (sha e07e9085...). The candidate PDF is versioned under sources/raw/bootstrap_v1/."}
+(ROOT / "docs" / "BA_ST_MVA_REFRESH_DIFF_V1.json").write_text(json.dumps(doc, ensure_ascii=False, indent=1, default=list), encoding="utf-8")
+print({k: (v if not isinstance(v, list) else len(v)) for k, v in doc.items() if k not in ("affected_products_by_database", "items_changed")}); print(affected)

fiscal/scripts/bloco2_pis_cofins_cross_db.py

@@ -0,0 +1,95 @@
+"""Missão 2 / Bloco 2.1 — evidência cruzada PIS/COFINS cadastro-vs-emissão, somente leitura, nos 6 bancos.
+Nunca escreve. Não decide regra fiscal: só conta e cruza fatos.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+from collections import Counter
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+import fdb  # noqa: E402
+import run_fiscal_decision_v1 as base  # noqa: E402
+from gti_fiscal_agent import company_context as cc  # noqa: E402
+
+DBS = {
+    "GTI": (r"D:\PROJETOS\GTISISTEMAS\Banco\GTI.FDB", {}),
+    "TESTESOFICIAIS": (str(ROOT / "TESTESOFICIAIS.FDB"), {}),
+    "CONSTRUCAO": (str(ROOT / "Banco" / "CONSTRUCAO.FDB"), {"company_code": "000001"}),
+    "MMMODAS": (str(ROOT / "Banco" / "MMMODAS.FDB"), {"company_code": "000001", "crt_source": "EMISSOR"}),
+    "RINCAO": (str(ROOT / "Banco" / "RINCAO.FDB"), {"company_code": "000001", "crt_source": "EMISSOR"}),
+    "UNIAO": (str(ROOT / "Banco" / "UNIAO.FDB"), {"company_code": "000001", "crt_source": "EMISSOR"}),
+}
+
+
+def connect(path):
+    return fdb.connect(database=path, user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"],
+                        fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"), isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+
+
+def analyze_one(name, path, cfg):
+    conn = connect(path); cur = conn.cursor()
+    company = cc.resolve(cc.collect_evidence(cur), cc.config_from_env({("COMPANY_CODE" if k == "company_code" else "COMPANY_CRT_SOURCE"): v for k, v in cfg.items()}))
+    out = {"name": name, "company_status": company["status"], "crt": company.get("company_crt"), "uf": company.get("company_uf")}
+    try:
+        cur.execute("SELECT COUNT(*), COUNT(NULLIF(TRIM(CST_PIS_COFINS),'')) FROM NFCE_ITENS")
+        tot, nonblank = cur.fetchone()
+        out["items_total"] = tot; out["items_cst_pis_cofins_filled"] = nonblank
+        out["pct_cst_filled"] = round(100.0 * nonblank / tot, 2) if tot else None
+    except Exception as e:  # noqa: BLE001
+        out["items_error"] = str(e)[:150]; conn.close(); return out
+    cur.execute("SELECT TRIM(CST_PIS_COFINS), COUNT(*) FROM NFCE_ITENS WHERE CST_PIS_COFINS IS NOT NULL GROUP BY 1 ORDER BY 2 DESC")
+    out["cst_distribution"] = {(r[0] or "(blank)"): r[1] for r in cur.fetchall()}
+    try:
+        cur.execute("SELECT EXTRACT(YEAR FROM DATA), COUNT(*), COUNT(NULLIF(TRIM(CST_PIS_COFINS),'')) FROM NFCE_ITENS GROUP BY 1 ORDER BY 1")
+        out["by_year"] = {int(y): {"items": t, "cst_filled": f} for y, t, f in cur.fetchall() if y is not None}
+    except Exception as e:  # noqa: BLE001
+        out["by_year_error"] = str(e)[:150]
+    try:
+        cur.execute("SELECT ROUND(ALIQUOTA_PIS,4), COUNT(*) FROM NFCE_ITENS WHERE ALIQUOTA_PIS IS NOT NULL GROUP BY 1 ORDER BY 2 DESC")
+        out["aliquota_pis_distribution"] = {str(r[0]): r[1] for r in cur.fetchmany(10)}
+        cur.execute("SELECT ROUND(ALIQUOTA_COFINS,4), COUNT(*) FROM NFCE_ITENS WHERE ALIQUOTA_COFINS IS NOT NULL GROUP BY 1 ORDER BY 2 DESC")
+        out["aliquota_cofins_distribution"] = {str(r[0]): r[1] for r in cur.fetchmany(10)}
+    except Exception as e:  # noqa: BLE001
+        out["aliquota_error"] = str(e)[:150]
+    # cadastro vs emissão, apenas nos itens cujo NCM emitido == NCM cadastrado (join identity-consistent, evita o viés de 2022-12 já documentado)
+    try:
+        cur.execute("""
+            SELECT COUNT(*),
+                   SUM(CASE WHEN TRIM(COALESCE(p.CLASSIFICACAO_FISCAL,'')) != '' AND p.CLASSIFICACAO_FISCAL = i.NCM THEN 1 ELSE 0 END)
+            FROM NFCE_ITENS i JOIN C000025 p ON p.CODIGO = i.CODPRODUTO
+        """)
+        joined_tot, identity_consistent = cur.fetchone()
+        out["identity_consistent_items"] = identity_consistent
+        cur.execute("""
+            SELECT COUNT(*)
+            FROM NFCE_ITENS i JOIN C000025 p ON p.CODIGO = i.CODPRODUTO
+            WHERE p.CLASSIFICACAO_FISCAL = i.NCM
+              AND COALESCE(TRIM(p.CST_ENTRADA),'') = '' -- produto sem CST/PIS cadastral (a maioria)
+              AND COALESCE(TRIM(i.CST_PIS_COFINS),'') != ''
+        """)
+        out["emitted_cst_present_when_cadastro_blank"] = cur.fetchone()[0]
+    except Exception as e:  # noqa: BLE001
+        out["cadastro_vs_emissao_error"] = str(e)[:150]
+    conn.close()
+    return out
+
+
+def main():
+    base.load_dotenv(ROOT / ".env")
+    results = {}
+    for name, (path, cfg) in DBS.items():
+        print(f"== {name}", flush=True)
+        try:
+            results[name] = analyze_one(name, path, cfg)
+        except Exception as e:  # noqa: BLE001
+            results[name] = {"name": name, "error": str(e)[:300]}
+        print(json.dumps(results[name], ensure_ascii=False, indent=1, default=str)[:800], flush=True)
+    out_path = ROOT / "docs" / "runs" / "BLOCO2_PIS_COFINS_CROSS_DB_V1.json"
+    out_path.write_text(json.dumps(results, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    print(f"-> {out_path}")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/blocoB_pis_cofins_source.py

@@ -0,0 +1,81 @@
+"""Missão 3 / Bloco B — de onde vem o CST/alíquota de PIS/COFINS emitido, somente leitura.
+Testa correlação e determinismo por NCM, CODGRUPO (via C000025), CFOP, CSOSN/CST_ICMS,
+GRUPO_ICMS. Não decide regra fiscal - só mede taxa de reprodução.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+from collections import Counter, defaultdict
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+import fdb  # noqa: E402
+import run_fiscal_decision_v1 as base  # noqa: E402
+
+DBS = {
+    "GTI": r"D:\PROJETOS\GTISISTEMAS\Banco\GTI.FDB",
+    "CONSTRUCAO": str(ROOT / "Banco" / "CONSTRUCAO.FDB"),
+    "MMMODAS": str(ROOT / "Banco" / "MMMODAS.FDB"),
+    "RINCAO": str(ROOT / "Banco" / "RINCAO.FDB"),
+    "UNIAO": str(ROOT / "Banco" / "UNIAO.FDB"),
+}
+
+
+def connect(path):
+    return fdb.connect(database=path, user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"],
+                        fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"), isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+
+
+def analyze(name, path):
+    conn = connect(path); cur = conn.cursor()
+    cur.execute("SELECT COUNT(*), COUNT(NULLIF(TRIM(CST_PIS_COFINS),'')) FROM NFCE_ITENS")
+    tot, filled = cur.fetchone()
+    out = {"name": name, "items_total": tot, "items_cst_filled": filled}
+    if filled == 0:
+        out["conclusion"] = "NAO_APLICAVEL_SEM_DADOS_PARA_CORRELACIONAR"
+        conn.close()
+        return out
+    # candidate determinants, only over the filled subset
+    for dim, expr in (("NCM", "i.NCM"), ("CODGRUPO", "p.CODGRUPO"), ("CFOP", "i.CFOP"), ("CSOSN", "i.CSOSN"), ("GRUPO_ICMS", "i.GRUPO_ICMS")):
+        try:
+            cur.execute(f"""
+                SELECT {expr}, TRIM(i.CST_PIS_COFINS), COUNT(*)
+                FROM NFCE_ITENS i LEFT JOIN C000025 p ON p.CODIGO = i.CODPRODUTO
+                WHERE COALESCE(TRIM(i.CST_PIS_COFINS),'') != ''
+                GROUP BY 1, 2
+            """)
+            rows = cur.fetchall()
+            by_key = defaultdict(Counter)
+            for k, cst, n in rows:
+                by_key[k][cst] += n
+            deterministic = sum(sum(c.values()) for c in by_key.values() if len(c) == 1)
+            total_filled_dim = sum(sum(c.values()) for c in by_key.values())
+            out[f"determinism_{dim}"] = {"distinct_keys": len(by_key), "items_covered": total_filled_dim,
+                                         "items_with_single_cst_for_key": deterministic,
+                                         "reproduction_rate_pct": round(100.0 * deterministic / total_filled_dim, 2) if total_filled_dim else None}
+        except Exception as e:  # noqa: BLE001
+            out[f"determinism_{dim}_error"] = str(e)[:150]
+    # aliquota_pis fill vs cst fill: same items or different?
+    cur.execute("SELECT COUNT(*) FROM NFCE_ITENS WHERE ALIQUOTA_PIS IS NOT NULL AND COALESCE(TRIM(CST_PIS_COFINS),'')=''")
+    out["aliquota_filled_but_cst_blank"] = cur.fetchone()[0]
+    cur.execute("SELECT COUNT(*) FROM NFCE_ITENS WHERE ALIQUOTA_PIS IS NULL AND COALESCE(TRIM(CST_PIS_COFINS),'')!=''")
+    out["cst_filled_but_aliquota_null"] = cur.fetchone()[0]
+    conn.close()
+    return out
+
+
+def main():
+    base.load_dotenv(ROOT / ".env")
+    results = {}
+    for name, path in DBS.items():
+        print(f"== {name}", flush=True)
+        results[name] = analyze(name, path)
+        print(json.dumps(results[name], ensure_ascii=False, indent=1, default=str), flush=True)
+    out_path = ROOT / "docs" / "runs" / "BLOCOB_PIS_COFINS_SOURCE_V1.json"
+    out_path.write_text(json.dumps(results, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    print(f"-> {out_path}")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/build_agent_package.py

@@ -0,0 +1,74 @@
+"""Build the GTI Fiscal Agent Windows package (zip) and verify it contains no secrets.
+
+    python scripts/build_agent_package.py            -> dist/GTIFiscalAgent-<version>.zip (+ .sha256)
+
+The zip root is the install folder:
+  gti-agent.ps1 / gti-agent.cmd / requirements-agent.txt / agent.env.template / pilot-construcao.env.example / profiles/
+  agent/{src,scripts,service}, scripts/firebird_write_executor.py, central/app/{engine modules}, VERSION, MANIFEST.json
+"""
+import hashlib
+import json
+import re
+import sys
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+VERSION = (ROOT / "release" / "VERSION").read_text(encoding="utf-8").strip()
+NAME = f"GTIFiscalAgent-{VERSION}"
+
+INCLUDE = [  # (source, destination inside the package)
+    *[(p, str(p.relative_to(ROOT)).replace("\\", "/")) for p in sorted((ROOT / "agent" / "src" / "gti_fiscal_agent").glob("*.py"))],
+    (ROOT / "agent" / "scripts" / "run_agent_service.py", "agent/scripts/run_agent_service.py"),
+    (ROOT / "agent" / "scripts" / "preflight.py", "agent/scripts/preflight.py"),
+    (ROOT / "agent" / "service" / "gti_agent_windows_service.py", "agent/service/gti_agent_windows_service.py"),
+    (ROOT / "scripts" / "firebird_write_executor.py", "scripts/firebird_write_executor.py"),
+    (ROOT / "central" / "__init__.py", "central/__init__.py"),
+    *[(ROOT / "central" / "app" / f, f"central/app/{f}") for f in ("__init__.py", "fiscal_decision.py", "dry_run_planner.py", "product_defaults.py", "icms_context.py")],
+    *[(p, p.name) for p in sorted((ROOT / "deploy" / "agent-windows").glob("*")) if p.is_file()],
+    *[(p, f"profiles/{p.name}") for p in sorted((ROOT / "deploy" / "agent-windows" / "profiles").glob("*")) if p.is_file()],
+    (ROOT / "release" / "VERSION", "VERSION"),
+]
+SECRET_PATTERNS = [
+    (re.compile(r"^[ 	]*(AGENT_TOKEN|FB_PASSWORD|POSTGRES_PASSWORD)[ 	]*=[ 	]*\S+", re.M), "non-empty secret assignment"),
+    (re.compile(r"masterkey", re.I), "default Firebird password"),
+    (re.compile(r"[A-Za-z0-9_\-]{40,}"), "long token-like string"),
+]
+ALLOWED_LONG = re.compile(r"^[A-Za-z0-9_\-]{40,}$")
+
+
+def scan(name, data):
+    if name.endswith((".ps1", ".cmd", ".py", ".txt", ".example", ".template", "VERSION")):
+        text = data.decode("utf-8", "replace")
+        for rx, why in SECRET_PATTERNS:
+            for m in rx.finditer(text):
+                token = m.group(0)
+                if why == "long token-like string" and (token.startswith(("_", "-")) or "_" in token and token.count("_") > 3 or token.isalpha()):
+                    continue  # identifiers / prose, not a secret
+                if why == "long token-like string" and not re.search(r"\d", token):
+                    continue
+                if why == "long token-like string" and re.fullmatch(r"[0-9a-f]{64}", token):
+                    continue  # schema fingerprint (public SHA-256), not a secret
+                raise SystemExit(f"secret scan failed in {name}: {why}: {token[:6]}...")
+
+
+def main():
+    dist = ROOT / "dist"
+    dist.mkdir(exist_ok=True)
+    out = dist / f"{NAME}.zip"
+    manifest = {"name": NAME, "version": VERSION, "files": {}}
+    with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
+        for src, dst in INCLUDE:
+            data = Path(src).read_bytes()
+            assert not dst.endswith((".env", ".sqlite", ".log", ".FDB")), dst
+            scan(dst, data)
+            manifest["files"][dst] = hashlib.sha256(data).hexdigest()
+            z.writestr(f"{NAME}/{dst}", data)
+        z.writestr(f"{NAME}/MANIFEST.json", json.dumps(manifest, indent=1))
+    digest = hashlib.sha256(out.read_bytes()).hexdigest()
+    (dist / f"{NAME}.zip.sha256").write_text(f"{digest}  {out.name}\n", encoding="utf-8")
+    print(json.dumps({"package": str(out.relative_to(ROOT)), "files": len(manifest["files"]), "sha256": digest}))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/build_operator_company_questions.py

@@ -0,0 +1,58 @@
+"""docs/OPERATOR_COMPANY_QUESTIONS_V1.md: ONLY company-wide decisions (category C) in plain Portuguese, plus the residual counts. Read-only over the state files."""
+import gzip, json, pickle, sys
+from collections import Counter
+from pathlib import Path
+ROOT = Path(__file__).resolve().parents[1]; ST = ROOT / "docs/runs/local_completion"
+DBS = ["CONSTRUCAO", "MMMODAS", "RINCAO", "UNIAO", "TESTESOFICIAIS"]
+Q = json.loads((ROOT / "docs/LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json").read_text(encoding="utf-8"))["questions"]
+summ = {n: json.loads((ST / f"{n}_dryrun_summary.json").read_text(encoding="utf-8")) for n in DBS}
+ipi_cells, entry_dist, rows_n = {}, {}, {}
+for n in DBS:
+    snap = pickle.load(gzip.open(ST / f"{n}_before.pkl.gz", "rb")); cols = snap["columns"]
+    ipi_cells[n] = 0; rows_n[n] = len(snap["rows"])
+    for l in gzip.open(ST / f"{n}_second.ndjson.gz", "rt", encoding="utf-8"):
+        r = json.loads(l)
+        if r["field"] == "IPI" and r["status"] == "ALREADY_CORRECT" and r["before"] not in (None, ""):
+            ipi_cells[n] += 1
+    entry_dist[n] = Counter((r[cols.index("CFOP_ENTRADA")] or "").strip()[:1] or "(vazio)" for r in snap["rows"].values())
+crt = {n: summ[n]["company"]["crt"] for n in DBS}
+by = lambda key: [q for q in Q if q["KEY"] == key and q["CATEGORY"] == "C"]  # noqa: E731
+regime = {"1": "Simples Nacional", "3": "Regime normal (Lucro Presumido/Real)"}
+out = ["# Perguntas de empresa — respostas necessárias ANTES da camada de IA", "",
+       "Só entram decisões que valem para a **empresa inteira**. Nada aqui é preenchido automaticamente: sem resposta, as células continuam pendentes.",
+       "Como responder: preencher a coluna `VALUE` da linha do mesmo QUESTION_ID em `docs/LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.csv` e importar com `scripts/import_fiscal_context.py`.", ""]
+n_q = 0; cells_total = 0
+def block(qid, banco, pergunta, opcoes, rec, prods, cells, expl):
+    global n_q, cells_total
+    n_q += 1; cells_total += cells
+    out.extend([f"### {qid} — {banco}", f"- **Pergunta:** {pergunta}", f"- **Opções:** {opcoes}", f"- **Recomendação:** {rec}", f"- **Produtos afetados:** {prods}", f"- **Células afetadas:** {cells}", f"- **Explicação:** {expl}", ""])
+out.append("## 1. Perfil de PIS/COFINS (por empresa)")
+for q in by("pis_cofins_profile"):
+    n = q["DATABASE"]
+    block(q["QUESTION_ID"], f"{n} ({regime.get(crt[n], crt[n])})", "Qual o enquadramento de PIS/COFINS desta empresa para produtos que NÃO estão em regime especial (monofásico, alíquota zero, etc.)?",
+          "JSON com pis_in_cst, pis_out_cst, pis_rate, cofins_in_cst, cofins_out_cst, cofins_rate (CSTs da tabela oficial 4.3.3/4.3.4). Ex. regime não cumulativo: saída 01, alíquotas 1,65 / 7,6; cumulativo: 0,65 / 3,0",
+          "nenhuma provada (depende do regime tributário real da empresa: cumulativo ou não cumulativo, dado que só o contador confirma)", q["PRODUCTS_AFFECTED"], q["CELLS"],
+          "A tabela oficial da Receita já resolveu os produtos em regime especial; os demais dependem do enquadramento da empresa. " + ("Nesta base o SGV não usa estes campos na emissão (100% dos itens de NFC-e saíram sem CST de PIS/COFINS); a resposta só completa poucos produtos com valor inválido no cadastro." if summ[n]["company"].get("pis_cofins_unused_by_emission") else "O histórico de NFC-e desta base emite CST de PIS/COFINS preenchido, então o campo do produto é usado na emissão."))
+out.append("## 2. Escopo das compras (CFOP de entrada)")
+for q in by("entry_scope"):
+    n = q["DATABASE"]; d = entry_dist[n]; tot = sum(d.values())
+    block(q["QUESTION_ID"], f"{n}", "As compras de mercadoria desta empresa são, em regra, dentro do estado (INTRA, CFOP 1xxx) ou de outro estado (INTER, CFOP 2xxx)?",
+          "INTRA | INTER", f"nenhuma provada. Só informativo: nos cadastros existentes desta base, CFOP de entrada 1xxx = {d.get('1', 0)}, 2xxx = {d.get('2', 0)}, vazio = {d.get('(vazio)', 0)} de {tot} produtos (declarações históricas, não prova de regra)",
+          q["PRODUCTS_AFFECTED"], q["CELLS"], "Só é usado nos produtos cujo CFOP de entrada está vazio. Produtos que já têm CFOP de entrada válido não são alterados.")
+out.append("## 3. Alíquota padrão de ICMS")
+for q in by("icms_rate"):
+    block(q["QUESTION_ID"], q["DATABASE"], "Qual a alíquota interna de ICMS padrão desta empresa (regime normal)?", "número em % (ex.: 20,5)", "nenhuma provada (a alíquota depende da mercadoria; não vale 20,5% universal)", q["PRODUCTS_AFFECTED"], q["CELLS"],
+          "Um único produto da base de testes depende desta resposta. As demais empresas são Simples Nacional e não destacam ICMS: não perguntado.")
+out.append("## 4. IPI no cadastro de empresa varejista (STORE_IPI_PROFILE)")
+out.append("Evidência do próprio SGV: em TODAS as bases `CONTRIBUINTE_IPI = N`; 745 itens vendidos na base de testes de produtos com alíquota de IPI cadastrada geraram IPI = 0 (nenhum valor de IPI foi calculado), e mais de 1,6 milhão de itens vendidos nas demais bases também têm IPI 0. O campo do cadastro é, portanto, apenas referência para empresa não contribuinte. **O SGV não impõe preencher.** Decisão de política:")
+out.append("")
+for n in DBS:
+    n_q += 1; cells_total += ipi_cells[n]
+    out.extend([f"### QIPI-{n} — {n}", "- **Pergunta:** Guardar no cadastro dos produtos a alíquota oficial da TIPI como referência (mesmo a empresa não sendo indústria/importadora)?", "- **Opções:** `POPULATE_REFERENCE_RATE` (guardar) | `LEAVE_NOT_APPLICABLE` (deixar em branco)",
+                "- **Recomendação:** nenhuma (é política da empresa; ambas as opções são válidas)", f"- **Produtos afetados:** {ipi_cells[n]}", f"- **Células afetadas:** {ipi_cells[n]} (já gravadas com o valor oficial; se responder LEAVE_NOT_APPLICABLE, serão revertidas com `scripts/rollback_field.py`)",
+                "- **Explicação:** enquanto não houver resposta, nenhum novo valor de IPI é gravado. Chave: `store_ipi_profile` (escopo COMPANY).", ""])
+out.append("## 5. Origem da mercadoria — NÃO é decisão de empresa")
+out.append("A origem (0 a 8) é atributo real de cada mercadoria e o ERP não a registra em lugar nenhum (o primeiro dígito do CST é só preenchimento). **Não existe uma resposta padrão de empresa** e nenhum valor será assumido. Só responda por GRUPO/PRODUTO quando puder garantir (ex.: grupo inteiro de importados = 1). Essas perguntas continuam nos arquivos V2, fora desta lista.")
+out += ["", f"**Total desta lista: {n_q} perguntas de empresa.**"]
+(ROOT / "docs/OPERATOR_COMPANY_QUESTIONS_V1.md").write_text("\n".join(out) + "\n", encoding="utf-8")
+print(n_q, cells_total)

fiscal/scripts/build_questionnaire_v2.py

@@ -0,0 +1,58 @@
+"""Questionnaire V2: aggregates every remaining MANUAL_INPUT_REQUIRED cell (docs/runs/local_completion/*_second.ndjson.gz) into the fewest operator questions.
+Only categories C (company configuration), D (product-group/NCM configuration) and E (product fact) may become questions."""
+import csv, gzip, json, pickle, sys
+from collections import defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]; ST = ROOT / "docs" / "runs" / "local_completion"
+sys.path.insert(0, str(ROOT))
+from central.app.context_keys import ENUMS  # noqa: E402
+
+DBS = ["CONSTRUCAO", "MMMODAS", "RINCAO", "UNIAO", "TESTESOFICIAIS"]
+CAT = {"origin": ("E", "COMPANY"), "pis_cofins_profile": ("C", "COMPANY"), "entry_scope": ("C", "COMPANY"), "icms_rate": ("C", "COMPANY"), "cest": ("D", "NCM"), "ex_tipi": ("D", "NCM"),
+       "st_withheld": ("D", "GROUP"), "st_status": ("D", "GROUP"), "icms_treatment": ("D", "GROUP"), "product_role": ("D", "GROUP"), "ncm": ("E", "PRODUCT"), "duplicate_code": ("E", "PRODUCT")}
+QUESTION = {"origin": "Qual a origem da mercadoria (0-8) dos produtos {scope}? (nenhuma evidencia no ERP; o digito do CST e apenas preenchimento)",
+            "pis_cofins_profile": "Qual o perfil PIS/COFINS da empresa (CST de entrada/saida e aliquotas)? JSON com pis_in_cst, pis_out_cst, pis_rate, cofins_in_cst, cofins_out_cst, cofins_rate",
+            "entry_scope": "As compras de mercadoria desta empresa sao predominantemente INTRA (dentro da UF) ou INTER (outra UF)?",
+            "icms_rate": "Qual a aliquota de ICMS padrao desta empresa (regime normal)?",
+            "cest": "Qual o CEST correto para o NCM {scope} (ou NONE quando o produto nao esta sujeito)?",
+            "ex_tipi": "Qual o EX da TIPI aplicavel ao NCM {scope} (ou NONE)?",
+            "st_withheld": "Os produtos {scope} sujeitos a ST tem o ICMS-ST ja retido na compra (Y/N)?",
+            "st_status": "Os produtos {scope} estao sujeitos a ST (SUBJECT/NOT_SUBJECT)? O ERP declara ST retida mas a tabela oficial nao lista o NCM",
+            "icms_treatment": "Qual o tratamento de ICMS dos produtos {scope}?",
+            "product_role": "Os produtos {scope} sao revenda, producao propria, insumo ou servico?",
+            "ncm": "Qual o NCM correto do produto {scope} (o atual nao existe na tabela oficial)?",
+            "duplicate_code": "O CODIGO {scope} aparece em 2 linhas fisicas (violacao de PK na copia); corrigir a integridade do banco (gfix/validate) antes de classificar"}
+WHY = {"origin": "CST/CSOSN e a origem do NF-e dependem dela; nao pode ser presumida 0", "pis_cofins_profile": "PIS/COFINS fora dos regimes especiais das tabelas SPED 4.3.x", "entry_scope": "CFOP de entrada (1xxx vs 2xxx)",
+       "icms_rate": "aliquota interna", "cest": "CEST oficial para o NCM tem varios candidatos ou o CEST do ERP nao consta da lista oficial", "ex_tipi": "varias linhas TIPI com aliquotas diferentes para o NCM",
+       "st_withheld": "ST comprovada pela tabela BA mas retencao desconhecida", "st_status": "conflito entre declaracao do ERP e tabela oficial", "icms_treatment": "CST de ICMS nao derivavel", "product_role": "revenda/producao define CFOP e IPPT",
+       "ncm": "NCM invalido bloqueia IPI/EX/CEST/ST/CFOP/CSOSN", "duplicate_code": "UPDATE por CODIGO exige rowcount 1"}
+agg = defaultdict(lambda: {"products": set(), "cells": 0, "fields": defaultdict(int), "examples": []})
+for n in DBS:
+    snap = pickle.load(gzip.open(ST / f"{n}_before.pkl.gz", "rb")); cols = snap["columns"]; rows = snap["rows"]
+    for l in gzip.open(ST / f"{n}_second.ndjson.gz", "rt", encoding="utf-8"):
+        r = json.loads(l)
+        if r["status"] != "MANUAL_INPUT_REQUIRED":
+            continue
+        k = r["input_key"]; cat, scope = CAT[k]; row = rows.get(r["codigo"]); g = (row[cols.index("CODGRUPO")] if row else None); ncm = (row[cols.index("CLASSIFICACAO_FISCAL")] if row else None)
+        sk = {"COMPANY": "", "GROUP": g or "", "NCM": ncm or "", "PRODUCT": r["codigo"]}[scope]
+        a = agg[(n, k, scope, sk)]; a["products"].add(r["row_key"]); a["cells"] += 1; a["fields"][r["field"]] += 1
+        if len(a["examples"]) < 3 and row: a["examples"].append(row[cols.index("PRODUTO")])
+out = []
+for (n, k, scope, sk), a in agg.items():
+    cat = CAT[k][0]
+    opts = sorted(ENUMS[k]) if k in ENUMS else ("JSON" if k == "pis_cofins_profile" else "7 digits or NONE" if k == "cest" else "8 digits" if k == "ncm" else "free")
+    who = "toda a empresa" if scope == "COMPANY" else f"{scope} {sk}"
+    out.append({"DATABASE": n, "COMPANY": n, "SCOPE": scope, "GROUP": sk if scope == "GROUP" else "", "NCM": sk if scope == "NCM" else "", "FIELD": "|".join(sorted(a["fields"])), "KEY": k, "CATEGORY": cat,
+                "QUESTION": QUESTION[k].format(scope=who), "VALID_OPTIONS": opts, "PRODUCTS_AFFECTED": len(a["products"]), "WHY_NEEDED": WHY[k], "WHAT_IT_WILL_RESOLVE": f"{a['cells']} celulas", "CELLS": a["cells"],
+                "EXAMPLES": "; ".join(a["examples"])})
+out.sort(key=lambda x: -x["CELLS"])
+for i, q in enumerate(out, 1): q["QUESTION_ID"] = f"Q{i:04d}"
+(ROOT / "docs" / "LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json").write_text(json.dumps({"artifact": "LOCAL_FISCAL_CONTEXT_QUESTIONS_V2", "total_questions": len(out), "total_cells": sum(q["CELLS"] for q in out), "questions": out}, ensure_ascii=False, indent=1), encoding="utf-8")
+hdr = ["QUESTION_ID", "DATABASE", "COMPANY", "SCOPE", "GROUP", "NCM", "FIELD", "KEY", "CATEGORY", "QUESTION", "VALID_OPTIONS", "PRODUCTS_AFFECTED", "WHY_NEEDED", "WHAT_IT_WILL_RESOLVE", "CELLS", "EXAMPLES", "VALUE"]
+with open(ROOT / "docs" / "LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.csv", "w", newline="", encoding="utf-8-sig") as f:
+    w = csv.DictWriter(f, fieldnames=hdr, extrasaction="ignore"); w.writeheader()
+    for q in out: w.writerow({**q, "VALID_OPTIONS": q["VALID_OPTIONS"] if isinstance(q["VALID_OPTIONS"], str) else "|".join(q["VALID_OPTIONS"]), "VALUE": ""})
+from collections import Counter
+print(len(out), sum(q["CELLS"] for q in out), dict(Counter(q["CATEGORY"] for q in out)), dict(Counter(q["KEY"] for q in out)))
+print([(q["QUESTION_ID"], q["DATABASE"], q["KEY"], q["CELLS"]) for q in out[:8]])

fiscal/scripts/build_rtc_reference_data.py

@@ -0,0 +1,102 @@
+"""Build central/app/rtc_reference_data.py: the OFFICIAL cClassTrib catalog + the LC 214/2025 goods annexes as structured, hash-pinned reference data.
+
+    python scripts/build_rtc_reference_data.py
+
+Inputs (all official, already downloaded/hashed):
+  sources/raw/bootstrap_v1/cClassTrib 2026-06-22.xlsx   Portal Nacional NF-e cClassTrib table (parsed with the Hub's own parser)
+  sources_cache/wb_lc214.bin                            LC 214/2025 compiled (Planalto, through LC 227/2026), extracted to text
+
+Nothing here decides anything: it only turns the published texts into data with provenance. Item texts that carry a condition/exception are
+marked `clean=False` so the resolver never treats them as a deterministic match.
+"""
+import hashlib
+import html
+import json
+import re
+import sys
+from datetime import date
+from pathlib import Path
+from pprint import pformat
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from central.app.datasets.bootstrap_v1_extra import parse_rtc_cclasstrib  # noqa: E402
+
+XLSX = ROOT / "sources" / "raw" / "bootstrap_v1" / "cClassTrib 2026-06-22.xlsx"
+LC214 = ROOT / "sources_cache" / "wb_lc214.bin"
+ROMAN = {"I": 1, "II": 2, "III": 3, "IV": 4, "V": 5, "VI": 6, "VII": 7, "VIII": 8, "IX": 9, "X": 10, "XI": 11, "XII": 12, "XIII": 13, "XIV": 14, "XV": 15}
+RESTRICTION = re.compile(r"exceto|ressalv|desde que|em conformidade|requisitos|somente|exclusiv|quando|observad|salvo|apenas|conforme|vedad|\ba\)|\bb\)|\bex\b|não", re.I)
+CODE = re.compile(r"\b(\d{2}\.\d{2}(?:\.\d{1,2}){0,2}|\d{4}(?:\.\d{1,2}){1,3})\b")
+
+
+def lc214_text():
+    raw = LC214.read_bytes()
+    text = raw.decode("latin-1", errors="replace")
+    text = re.sub(r"<script.*?</script>|<style.*?</style>", "", text, flags=re.S)
+    text = html.unescape(re.sub(r"<[^>]+>", " ", text))
+    return raw, re.sub(r"[ \t\r\f\v]+", " ", text)
+
+
+def parse_annexes(text):
+    heads = [(m.start(), m.group(1)) for m in re.finditer(r"\n[ \xa0]*ANEXO ([IVXL]+)[ \xa0]*\n", text)]
+    blocks, seen = {}, set()
+    for i, (pos, roman) in enumerate(heads):
+        if roman in seen or roman not in ROMAN:
+            continue
+        # the goods annexes I..XV are the first occurrence of each numeral, before the Simples annexes (which repeat I..VII)
+        seen.add(roman)
+        end = heads[i + 1][0] if i + 1 < len(heads) else len(text)
+        blocks[roman] = text[pos:end]
+    out = {}
+    for roman, block in blocks.items():
+        head = " ".join(block[:600].split())
+        items, current, expected = [], None, 1
+        lines = [ln.strip() for ln in block.split("\n")]
+        for idx, ln in enumerate(lines):
+            if ln == str(expected):
+                nxt = next((x for x in lines[idx + 1:idx + 8] if x), "")
+                if nxt and not nxt.isdigit():
+                    current = {"item": expected, "text": []}
+                    items.append(current)
+                    expected += 1
+                    continue
+            if current is not None and ln:
+                current["text"].append(ln)
+        parsed = []
+        for it in items:
+            desc = " ".join(" ".join(it["text"]).split())
+            prefixes = sorted({re.sub(r"\D", "", c) for c in CODE.findall(desc)})
+            clean = not RESTRICTION.search(desc) and bool(prefixes)
+            parsed.append({"item": it["item"], "description": desc[:400], "prefixes": prefixes, "clean": clean})
+        out[roman] = {"number": ROMAN[roman], "title": head[:200], "revoked": "Revogado" in head, "items": parsed}
+    return out
+
+
+def main():
+    payload = parse_rtc_cclasstrib(XLSX.read_bytes())
+    official = []
+    for e in payload.entries:
+        ind = e["indicators"]
+        official.append({"code": e["cclasstrib"], "cst": e["cst"], "name": (e["name"] or "")[:160], "tipo_aliquota": e["tipo_aliquota"], "p_red_ibs": e["p_red_ibs"], "p_red_cbs": e["p_red_cbs"],
+                         "start": (e["d_ini_vig"] or "")[:10] or None, "end": (e["d_fim_vig"] or "")[:10] or None, "anexo": e.get("anexo"), "ind_nfe": ind.get("indNFe") == "1", "ind_nfce": ind.get("indNFCe") == "1"})
+    raw, text = lc214_text()
+    annexes = parse_annexes(text)
+    counts = {k: (len(v["items"]), sum(1 for i in v["items"] if i["clean"])) for k, v in annexes.items()}
+    module = ROOT / "central" / "app" / "rtc_reference_data.py"
+    catalog_meta = {"file": XLSX.name, "sha256": hashlib.sha256(XLSX.read_bytes()).hexdigest(), "publication": "2026-06-22", "source": "Portal Nacional da NF-e (cClassTrib)", "parser": payload.parser_version}
+    lc_meta = {"document": "Lei Complementar 214/2025 compiled (through LC 227/2026)", "url": "https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp214.htm", "sha256": hashlib.sha256(raw).hexdigest(),
+               "accessed_at": date.today().isoformat(), "fetched_via": "Internet Archive copy of the official URL"}
+    header = '"""GENERATED by scripts/build_rtc_reference_data.py - do not edit. Official cClassTrib catalog and LC 214/2025 goods annexes with provenance."""' + "\n\n"
+    body = "\n\n".join([
+        "OFFICIAL_CATALOG = " + pformat(catalog_meta, width=160),
+        "OFFICIAL_CCLASSTRIB = " + pformat(official, width=220),
+        "LC214_SOURCE = " + pformat(lc_meta, width=160),
+        "LC214_ANNEXES = " + pformat(annexes, width=220),
+    ]) + "\n"
+    module.write_text(header + body, encoding="utf-8")
+    (ROOT / "docs" / "sources" / "RTC_REFERENCE_MANIFEST_V1.json").write_text(json.dumps({"official_catalog": catalog_meta, "official_classes": len(official), "lc214": lc_meta, "annex_items_total_and_clean": counts}, ensure_ascii=False, indent=1), encoding="utf-8")
+    print(len(official), "official classes;", "annex items (total, clean):", counts)
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/build_sped_pis_cofins_dataset.py

@@ -0,0 +1,56 @@
+"""Parse the official SPED EFD-Contribuições tables 4.3.x (Word .doc, converted with antiword) into a versioned NCM-keyed dataset.
+Source: sped.rfb.gov.br/arquivo/download/<id> (current files, fetched directly on 2026-09-21).
+Writes docs/sources/SPED_PISCOFINS_TABLES_V3.json  (per table: source id, sha256 of the .doc, version text, entries {code, description, ncm_prefixes, start, end, pis_rate, cofins_rate})."""
+import datetime, hashlib, json, re, sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]; SRC = ROOT / "sources_cache" / "cur"
+TABLES = {  # sped item id -> (table, CST it defines for the SAIDA side, meaning)
+    1638: ("4.3.10", ["02", "04"], "MONOFASICA_OU_PAUTA"), 1642: ("4.3.12", ["05"], "SUBSTITUICAO_TRIBUTARIA"), 1643: ("4.3.13", ["06"], "ALIQUOTA_ZERO"),
+    1646: ("4.3.14", ["07"], "ISENTA"), 1651: ("4.3.15", ["08"], "SEM_INCIDENCIA"), 5786: ("4.3.11", ["03", "04"], "MONOFASICA_AD_REM")}
+NCM = re.compile(r"\d{4}(?:\.\d{2}(?:\.\d{2}(?:\.\d{2})?)?)?")
+DATE = re.compile(r"\d{2}/\d{4}|\d{2}/\d{2}/\d{4}")
+
+
+def parse(txt):
+    rows, cur = [], None
+    for line in txt.splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if cells and re.fullmatch(r"\d{3}", cells[0] or ""):
+            cur = {"code": cells[0], "cells": [[c] for c in cells[1:]]}; rows.append(cur)
+        elif cur is not None and len(cells) > 1 and not cells[0]:
+            for i, c in enumerate(cells[1:]):
+                if i < len(cur["cells"]) and c:
+                    cur["cells"][i].append(c)
+    return rows
+
+
+out = {"artifact": "SPED_PISCOFINS_TABLES_V3", "tables": {}}
+for sid, (tab, csts, meaning) in TABLES.items():
+    raw = (SRC / f"sped_{sid}.bin").read_bytes(); txt = (SRC / f"sped_{sid}.txt").read_text(encoding="utf-8", errors="replace")
+    hdr = (SRC / f"h_{sid}.txt").read_text(errors="replace"); lm = re.search(r"Last-Modified: (.*)", hdr); lm = lm.group(1).strip() if lm else None
+    head_all = " ".join(txt.splitlines()[:60])
+    ver = re.search(r"Vers[ãa]o (\d+(?:\.\d+)+)", head_all); eff = re.search(r"Atualizad[ao]s? em (\d{2}/\d{2}/\d{4})", head_all)
+    head = " ".join(l.strip() for l in txt.splitlines()[:8] if l.strip() and not l.startswith("|"))
+    entries = []
+    for r in parse(txt):
+        cells = [" ".join(c) for c in r["cells"]] or [""]; dcells = ["".join(c) for c in r["cells"]]
+        joined_ncm = cells[1] if len(cells) > 1 else ""
+        pref = sorted({m.group(0).replace(".", "") for m in NCM.finditer(joined_ncm)})
+        dates = [d for c in dcells[2:] for d in DATE.findall(c)]
+        rates = re.findall(r"\d+,\d+", " ".join(cells[2:4])) if tab in ("4.3.10", "4.3.12") else []
+        entries.append({"code": r["code"], "description": cells[0] if cells else "", "ncm_prefixes": pref, "applies_to_all_ncm": not pref and joined_ncm.strip() in ("-", ""), "start": dates[0] if dates else None, "end": dates[1] if len(dates) > 1 else None, "rates_text": rates})
+    out["tables"][tab] = {"sped_item": sid, "source_url": f"http://sped.rfb.gov.br/arquivo/download/{sid}", "download_date": datetime.date.today().isoformat(), "http_last_modified": lm, "version": ver.group(1) if ver else None, "effective_date": eff.group(1) if eff else None, "sha256_doc": hashlib.sha256(raw).hexdigest(), "version_text": head, "saida_cst": csts, "meaning": meaning,
+                          "fetched_via": "direct official download over http (sped.rfb.gov.br)", "entries": entries, "ncm_prefix_count": len({p for e in entries for p in e["ncm_prefixes"]})}
+    print(tab, len(entries), out["tables"][tab]["ncm_prefix_count"], head[:110])
+for sid, name in ((1629, "4.3.3"), (1630, "4.3.4")):
+    raw = (SRC / f"sped_{sid}.bin").read_bytes(); txt = (SRC / f"sped_{sid}.txt").read_text(encoding="utf-8", errors="replace")
+    cst = {}
+    for line in txt.splitlines():
+        m = re.match(r"\|(\d{2})\s*\|([^|]+)\|", line)
+        if m: cst[m.group(1)] = m.group(2).strip()
+    out["tables"][name] = {"sped_item": sid, "sha256_doc": hashlib.sha256(raw).hexdigest(), "cst_domain": cst}
+    print(name, sorted(cst))
+(ROOT / "docs" / "sources" / "SPED_PISCOFINS_TABLES_V3.json").write_text(json.dumps(out, ensure_ascii=False, indent=1), encoding="utf-8")

fiscal/scripts/build_windows_installer.ps1

@@ -0,0 +1,96 @@
+# Build the three Windows installer artifacts with PyInstaller:
+#
+#   dist/installer/GTIFiscalAgent-Setup-<version>.exe   (onefile, --uac-admin)  <- main download artifact
+#   dist/installer/GTIFiscalAgentService/<host>         (onedir)   <- embedded in Setup, extracted to Program Files
+#   dist/installer/Uninstall.exe                        (onefile, --uac-admin)  <- embedded in Setup, ARP uninstaller
+#   dist/installer/GTIFiscalAgent-Setup-<version>.exe.sha256
+#
+# Reproducibility = automated, repeatable, deterministic inputs + immutable
+# PUBLISHED release (byte-identical hashes are NOT required).
+#
+# Requires (fails fast if missing): python with PyInstaller, pywin32, fdb,
+# httpx; icacls for the ACL on credentials.bin.
+[CmdletBinding()]
+param(
+    [string]$Python = "python",
+    [switch]$SkipSetup = $false,
+    [switch]$SkipService = $false,
+    [switch]$SkipUninstall = $false
+)
+
+$ErrorActionPreference = "Stop"
+$Root = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+$Version = (Get-Content (Join-Path $Root "release\VERSION") -Raw).Trim()
+$Out = Join-Path $Root "dist\installer"
+$Work = Join-Path $Root "build\installer"
+$SpecDir = Join-Path $Root "build\installer"
+
+function Invoke-Step([string]$Title, [scriptblock]$Body) {
+    Write-Host "== $Title ==" -ForegroundColor Cyan
+    & $Body
+    if ($LASTEXITCODE -ne 0) { throw "$Title failed with exit code $LASTEXITCODE" }
+}
+
+Write-Host "Building GTI Fiscal Agent installer v$Version" -ForegroundColor Green
+
+$py = (Get-Command $Python).Source
+& $py -c "import PyInstaller, fdb, httpx, win32serviceutil; print('deps ok, pyinstaller', PyInstaller.__version__)"
+if ($LASTEXITCODE -ne 0) { throw "build environment is missing PyInstaller/fdb/httpx/pywin32" }
+if (-not (Get-Command "icacls" -ErrorAction SilentlyContinue)) { throw "missing required tool: icacls" }
+
+$Paths = @("--paths", (Join-Path $Root "agent\src"), "--paths", (Join-Path $Root "agent\scripts"),
+           "--paths", (Join-Path $Root "agent\service"), "--paths", (Join-Path $Root "central"))
+$Common = @("--noconfirm", "--clean", "--distpath", $Out, "--workpath", $Work, "--specpath", $SpecDir,
+            "--log-level", "WARN")
+# win32crypt is imported lazily inside credential_store (function body), so the
+# AST scan misses it; the agent service modules also need the pywin32 service libs.
+$Hidden = @("--hidden-import=win32timezone", "--hidden-import=win32crypt",
+            "--hidden-import=win32serviceutil", "--hidden-import=win32service",
+            "--hidden-import=win32event", "--hidden-import=servicemanager")
+# None of the reachable runtime modules import these (verified by tracing
+# __import__ while loading run_agent_service's full chain); they only add
+# ~100MB+ of dead weight via hook-gathered submodules. Exclude them.
+$Excludes = @("--exclude-module=numpy", "--exclude-module=PIL", "--exclude-module=yaml",
+              "--exclude-module=scipy", "--exclude-module=pandas", "--exclude-module=matplotlib",
+              "--exclude-module=openpyxl", "--exclude-module=jinja2")
+
+if (-not $SkipService) {
+    Invoke-Step "Build service host (onedir)" -Body {
+        & $py -m PyInstaller @Common @Paths @Hidden @Excludes "--onedir" `
+            "--name" "GTIFiscalAgentService" (Join-Path $Root "installer\service_main.py")
+    }
+}
+
+if (-not $SkipUninstall) {
+    Invoke-Step "Build Uninstall.exe (onefile, uac-admin)" -Body {
+        & $py -m PyInstaller @Common @Paths @Hidden @Excludes "--onefile" "--uac-admin" "--name" "Uninstall" `
+            (Join-Path $Root "installer\uninstall_main.py")
+    }
+}
+
+if (-not $SkipSetup) {
+    $ServiceData = (Join-Path $Out "GTIFiscalAgentService") + ";" + "GTIFiscalAgentService"
+    $UninstallData = (Join-Path $Out "Uninstall.exe") + ";" + "."
+    $ExecutorData = (Join-Path $Root "scripts\firebird_write_executor.py") + ";" + "scripts"
+    $VersionData = (Join-Path $Root "release\VERSION") + ";" + "."
+Invoke-Step "Build Setup.exe (onefile, uac-admin)" -Body {
+        & $py -m PyInstaller @Common @Paths @Hidden @Excludes "--onefile" "--uac-admin" "--name" "GTIFiscalAgent-Setup" `
+            "--add-data" $ServiceData "--add-data" $UninstallData "--add-data" $ExecutorData "--add-data" $VersionData `
+            (Join-Path $Root "installer\setup_main.py")
+    }
+}
+
+$BuiltSetup = Join-Path $Out "GTIFiscalAgent-Setup.exe"
+$FinalSetup = Join-Path $Out "GTIFiscalAgent-Setup-$Version.exe"
+if (Test-Path $BuiltSetup) {
+    Move-Item -Force $BuiltSetup $FinalSetup
+    $Digest = (Get-FileHash -Algorithm SHA256 -Path $FinalSetup).Hash.ToLowerInvariant()
+    Set-Content -Path "$FinalSetup.sha256" -Value "$Digest  $([IO.Path]::GetFileName($FinalSetup))`n" -NoNewline -Encoding Ascii
+    Write-Host "Installer: $FinalSetup" -ForegroundColor Green
+    Write-Host "sha256:    $Digest" -ForegroundColor Green
+} else {
+    Write-Host "Setup artifact not built (skipped); service host + Uninstall.exe still available under $Out" -ForegroundColor Yellow
+}
+
+Get-ChildItem $Out -Recurse | Select-Object FullName, Length | Format-Table -AutoSize
+Write-Host "Build complete." -ForegroundColor Green

fiscal/scripts/bulk_classify_in_container.py

@@ -0,0 +1,46 @@
+"""Runs INSIDE the fiscal-hub container (read-only on PostgreSQL): classifies [ncm, description] pairs with the
+production Classifier through a memoizing repository wrapper. Same code path as /v1/classify, minus HTTP and the
+classification_cache write; the wrapper only memoizes pure dataset lookups (datasets are static during the run).
+usage: python /tmp/bulk_classify_in_container.py /tmp/in.json /tmp/out.json
+"""
+import json
+import sys
+from functools import lru_cache
+
+from central.app.classification import Classifier
+from central.app.datasets.service import DatasetService
+from central.app.db import SessionLocal
+
+
+class Memo:
+    def __init__(self, service):
+        self._s = service; self._cache = {}
+
+    def __getattr__(self, name):
+        attr = getattr(self._s, name)
+        if not callable(attr):
+            return attr
+        def wrapped(*a, **kw):
+            key = (name, a, tuple(sorted(kw.items())))
+            try:
+                hash(key)
+            except TypeError:
+                return attr(*a, **kw)
+            if key not in self._cache:
+                self._cache[key] = attr(*a, **kw)
+            return self._cache[key]
+        return wrapped
+
+
+def main():
+    pairs = json.load(open(sys.argv[1], encoding="utf-8"))
+    out = []
+    with SessionLocal() as session:
+        classifier = Classifier(Memo(DatasetService(session)))
+        for ncm, desc in pairs:
+            out.append(classifier.classify({"current_ncm": ncm, "description": desc}))
+    json.dump(out, open(sys.argv[2], "w", encoding="utf-8"), ensure_ascii=False, default=str)
+    print(len(out))
+
+
+main()

fiscal/scripts/concurrency_sim.py

@@ -0,0 +1,73 @@
+"""Controlled concurrency simulation of whole-database classification against the LOCAL dev Hub.
+N simulated Agents each classify M products (read-only Firebird sample + Hub /classify, exactly the Agent's HubClient path).
+UNLIMITED = all N at once; LIMITED = only K at a time (what HEAVY_JOB_CONCURRENCY_LIMIT enforces at job claim). Samples the Hub container CPU/RAM (docker stats).
+    python scripts/concurrency_sim.py [--agents 8] [--products 2084] [--limit 3]"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path[:0] = [str(ROOT), str(ROOT / "scripts"), str(ROOT / "agent" / "src")]
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import local_completion as lc  # noqa: E402
+from gti_fiscal_agent import firebird_reader  # noqa: E402
+from gti_fiscal_agent.client import HubClient  # noqa: E402
+from gti_fiscal_agent.runner import to_hub_product  # noqa: E402
+
+
+def sampler(stop, samples):
+    while not stop.is_set():
+        out = subprocess.run(["docker", "stats", "--no-stream", "--format", "{{.CPUPerc}}|{{.MemUsage}}", "projeto-fiscal-hub-1"], capture_output=True, text=True).stdout.strip()
+        try:
+            cpu, mem = out.split("|"); samples.append((float(cpu.strip("%")), float(mem.split("/")[0].strip().replace("MiB", "").replace("GiB", "")) ))
+        except Exception:  # noqa: BLE001
+            pass
+        time.sleep(1)
+
+
+def run(agents, products, limit):
+    gate = threading.Semaphore(limit if limit else agents)
+    results, samples, stop = [], [], threading.Event()
+    threading.Thread(target=sampler, args=(stop, samples), daemon=True).start()
+
+    def one(i):
+        queued = time.time()
+        with gate:
+            started = time.time()
+            try:
+                client = HubClient(os.environ.get("HUB_URL", lc.HUB), os.environ["AGENT_DEV_TOKEN"])
+                client.classify_batch(products)
+                return {"agent": i, "queue_wait_s": round(started - queued, 1), "run_s": round(time.time() - started, 1), "ok": True}
+            except Exception as error:  # noqa: BLE001
+                return {"agent": i, "queue_wait_s": round(started - queued, 1), "run_s": round(time.time() - started, 1), "ok": False, "error": type(error).__name__}
+    t0 = time.time()
+    with ThreadPoolExecutor(agents) as pool:
+        results = list(pool.map(one, range(agents)))
+    wall = time.time() - t0
+    stop.set()
+    cpus = [c for c, _ in samples] or [0]; mems = [m for _, m in samples] or [0]
+    return {"limit": limit or "none", "wall_s": round(wall, 1), "products_per_s": round(agents * len(products) / wall, 1), "failures": sum(1 for r in results if not r["ok"]),
+            "max_run_s": max(r["run_s"] for r in results), "max_queue_wait_s": max(r["queue_wait_s"] for r in results), "hub_cpu_peak_pct": max(cpus), "hub_cpu_avg_pct": round(sum(cpus) / len(cpus), 1), "hub_mem_peak_mib": max(mems)}
+
+
+def main():
+    ap = argparse.ArgumentParser(); ap.add_argument("--agents", type=int, default=8); ap.add_argument("--products", type=int, default=2084); ap.add_argument("--limit", type=int, default=3)
+    a = ap.parse_args()
+    env = lc.env_for(lc.allowlist()["TESTESOFICIAIS"])
+    base = firebird_reader.read_products(env)
+    sample = [to_hub_product(p) for p in (base * (a.products // len(base) + 1))[:a.products]]
+    out = {"agents": a.agents, "products_per_agent": a.products, "runs": [run(a.agents, sample, 0), run(a.agents, sample, a.limit)]}
+    print(json.dumps(out, indent=1))
+    (ROOT / "docs" / "runs" / "final_corpus" / "concurrency_sim.json").write_text(json.dumps(out, indent=1), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/deploy_hub.ps1

@@ -0,0 +1,80 @@
+# Official production deploy of the GTI Fiscal Hub (10.0.10.117). Run by the OPERATOR, outside Claude Code:
+#   powershell -ExecutionPolicy Bypass -File .\scripts\deploy_hub.ps1 [-PublishAgent] [-Version 1.1.5] [-SkipTests] [-DryRun]
+# SSH password: env GTI_SSH_PASSWORD, else GTI_SSH_PASSWORD=... in .env.local (gitignored). Never printed or logged.
+[CmdletBinding()]
+param(
+    [string]$Version = "",
+    [switch]$PublishAgent,
+    [switch]$SkipTests,
+    [switch]$DryRun,
+    [string]$Python = "python"
+)
+$ErrorActionPreference = "Stop"
+$Root = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+Set-Location $Root
+$LogDir = Join-Path $Root "logs"; New-Item -ItemType Directory -Force $LogDir | Out-Null
+$Log = Join-Path $LogDir ("deploy-{0}.log" -f (Get-Date -Format "yyyyMMdd-HHmmss"))
+Start-Transcript -Path $Log | Out-Null
+try {
+    if (-not $Version) { $Version = (Get-Content (Join-Path $Root "release\VERSION") -Raw).Trim() }
+
+    # 3. credential: process env wins, then .env.local
+    $src = "env"
+    if (-not $env:GTI_SSH_PASSWORD) {
+        $envFile = Join-Path $Root ".env.local"
+        if (Test-Path $envFile) {
+            $line = Get-Content $envFile | Where-Object { $_ -match '^\s*GTI_SSH_PASSWORD\s*=' } | Select-Object -First 1
+            if ($line) { $env:GTI_SSH_PASSWORD = ($line -replace '^\s*GTI_SSH_PASSWORD\s*=\s*', '').Trim().Trim('"').Trim("'"); $src = ".env.local" }
+        }
+    }
+    if (-not $env:GTI_SSH_PASSWORD) { throw "GTI_SSH_PASSWORD not found in the environment or .env.local" }
+    Write-Host "SSH_AUTH_SOURCE=$src PASSWORD_LOGGED=false"
+
+    # 2. local pre-checks
+    git check-ignore -q .env.local
+    if ($LASTEXITCODE -ne 0 -and (Test-Path ".env.local")) { throw ".env.local is not gitignored" }
+    $dirty = git status --porcelain
+    if ($dirty) { throw "working tree is not clean - commit or stash first:`n$dirty" }
+    $branch = git rev-parse --abbrev-ref HEAD; $head = git rev-parse --short HEAD
+    Write-Host "BRANCH=$branch HEAD=$head VERSION=$Version"
+    $fileVersion = (Get-Content (Join-Path $Root "release\VERSION") -Raw).Trim()
+    if ($fileVersion -ne $Version) { throw "release/VERSION is $fileVersion but -Version is $Version" }
+    if ($PublishAgent) {
+        $exe = Join-Path $Root "dist\installer\GTIFiscalAgent-Setup-$Version.exe"
+        if (-not (Test-Path $exe)) { throw "installer not built: $exe (run scripts\build_windows_installer.ps1)" }
+    }
+    if (-not $SkipTests) {
+        # per-run basetemp: some tests ACL-lock their tmp dirs, which breaks pytest's shared default temp root
+        $base = Join-Path (Join-Path $Root ".pytmp") ("run-" + (Get-Date -Format "yyyyMMddHHmmss"))
+        & $Python -m pytest tests central/tests agent/tests -q -p no:cacheprovider --basetemp=$base
+        if ($LASTEXITCODE -ne 0) { throw "tests failed - deploy aborted" }
+    }
+
+    # 4. route/SSH recovery: reconnect the existing Windows VPN profile "GTI" (saved credentials) and retry
+    $reachable = $false
+    for ($i = 1; $i -le 3 -and -not $reachable; $i++) {
+        $reachable = (Test-NetConnection 10.0.10.117 -Port 22 -WarningAction SilentlyContinue).TcpTestSucceeded
+        if (-not $reachable) {
+            Write-Host "SSH_UNREACHABLE attempt=$i - reconnecting VPN profile GTI"
+            rasdial GTI | Out-Null
+            Start-Sleep -Seconds (10 * $i)
+        }
+    }
+    if (-not $reachable) { throw "FAILED_STAGE=network REMOTE_ERROR=10.0.10.117:22 unreachable after 3 attempts (VPN profile GTI)" }
+    Write-Host "SSH_ROUTE_OK"
+    Remove-Item (Join-Path $LogDir "last_deploy_result.json") -ErrorAction SilentlyContinue
+
+    $deployArgs = @("scripts\deploy_hub_remote.py", "--version", $Version)
+    if ($DryRun) { $deployArgs += "--dry-run" }
+    if ($PublishAgent) { $deployArgs += "--publish-agent" }
+    & $Python @deployArgs
+    if ($LASTEXITCODE -ne 0) {
+        $res = Join-Path $LogDir "last_deploy_result.json"
+        $detail = if (Test-Path $res) { $j = Get-Content $res -Raw | ConvertFrom-Json; "FAILED_STAGE/ERROR=$($j.error) ROLLBACK_REQUIRED=$($j.rollback_required)" } else { "no result file (see $Log)" }
+        throw "remote deploy failed: $detail"
+    }
+    Write-Host "DEPLOY_SCRIPT_OK log=$Log"
+} finally {
+    Remove-Item Env:GTI_SSH_PASSWORD -ErrorAction SilentlyContinue
+    Stop-Transcript | Out-Null
+}

fiscal/scripts/deploy_hub_remote.py

@@ -0,0 +1,224 @@
+"""Remote half of scripts/deploy_hub.ps1 (the official GTI Fiscal Hub deploy). Not meant to be run directly.
+
+SSH password: env GTI_SSH_PASSWORD only (never argv, never logged). Every output line is scrubbed of it.
+Flow: preflight -> backup (abort on failure) -> upload git-archive of HEAD -> extract IN PLACE (keeps .env,
+compose overrides and volumes) -> build/up (alembic upgrade head runs at container start) -> health ->
+optional Agent release publish -> public smoke. A failure after production was touched restores the previous
+tree from the backup tarball and rebuilds; the Postgres volume is never removed or restored automatically."""
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import paramiko
+
+HOST = "10.0.10.117"
+USER = "administrador"
+REMOTE = "/home/administrador/gti-fiscal"
+COMPOSE_DIR = f"{REMOTE}/deploy/hub"
+COMPOSE = "docker compose -f docker-compose.prod.yml --env-file .env"
+HUB = "gti-fiscal-hub-fiscal-hub-1"
+PG = "gti-fiscal-hub-postgres-1"
+PUBLIC = "https://gtifiscal.gtigrupo.com.br"
+REPO = Path(__file__).resolve().parents[1]
+PASSWORD = os.environ.get("GTI_SSH_PASSWORD", "")
+SECRET_RE = re.compile(r"(?i)(password|passwd|token|secret)(\s*[=:]\s*)\S+")
+
+
+def log(msg: str) -> None:
+    text = str(msg)
+    if PASSWORD:
+        text = text.replace(PASSWORD, "***")
+    print(SECRET_RE.sub(r"\1\2***", text), flush=True)
+
+
+class Remote:
+    def __init__(self, dry: bool):
+        self.dry = dry
+        self.client = paramiko.SSHClient()
+        self.client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+        self.client.connect(HOST, username=USER, password=PASSWORD, timeout=20, look_for_keys=False, allow_agent=False)
+
+    def run(self, cmd: str, timeout: int = 600, check: bool = True, mutating: bool = True) -> str:
+        if self.dry and mutating:
+            log(f"[dry-run] $ {cmd}")
+            return ""
+        _, out, err = self.client.exec_command(cmd, timeout=timeout)
+        text = out.read().decode(errors="replace") + err.read().decode(errors="replace")
+        rc = out.channel.recv_exit_status()
+        log(f"$ {cmd}\n{text.rstrip()[-1500:]}")
+        if check and rc != 0:
+            raise RuntimeError(f"exit {rc}: {cmd[:120]} :: {text.strip()[-400:]}")
+        return text
+
+    def put(self, local: Path, remote: str) -> None:
+        if self.dry:
+            log(f"[dry-run] upload {local.name} -> {remote}")
+            return
+        self.client.open_sftp().put(str(local), remote)
+
+
+def wait_health(r: Remote, expected: str) -> None:
+    if r.dry:
+        log("[dry-run] health checks skipped")
+        return
+    for _ in range(30):
+        st = r.run(f"docker inspect -f '{{{{.State.Health.Status}}}}' {HUB} {PG}", check=False, mutating=False)
+        if st.split() == ["healthy", "healthy"]:
+            break
+        time.sleep(4)
+    else:
+        raise RuntimeError("containers did not become healthy")
+    probe = ("python -c \"import urllib.request as u;print(u.urlopen('http://localhost:8000/%s').read().decode())\"")
+    ver = json.loads(r.run(f"docker exec {HUB} " + probe % "version", mutating=False))
+    r.run(f"docker exec {HUB} " + probe % "health", mutating=False)
+    if ver.get("version") != expected:
+        raise RuntimeError(f"version mismatch: production {ver.get('version')} != expected {expected}")
+    log(f"HEALTH_OK version={ver.get('version')}")
+
+
+def public_smoke(expected: str) -> None:
+    for path in ("/health", "/version"):
+        with urllib.request.urlopen(PUBLIC + path, timeout=20) as resp:
+            body = resp.read().decode()
+            if resp.status != 200:
+                raise RuntimeError(f"public {path} -> {resp.status}")
+            if path == "/version" and json.loads(body).get("version") != expected:
+                raise RuntimeError("public version mismatch")
+    log(f"PUBLIC_HEALTH=200 PUBLIC_VERSION={expected}")
+
+
+def write_result(status: str, error: str, rollback: bool) -> None:
+    out = REPO / "logs"
+    out.mkdir(exist_ok=True)
+    text = json.dumps({"status": status, "error": SECRET_RE.sub(r"
***", error).replace(PASSWORD, "***"), "rollback_required": rollback})
+    (out / "last_deploy_result.json").write_text(text, encoding="utf-8")
+
+
+def public_extra() -> None:
+    body = urllib.request.urlopen("https://gtigerenciador.gtigrupo.com.br/login", timeout=20).status
+    log(f"GERENCIADOR_HEALTH={body}")
+    req = urllib.request.Request(PUBLIC + "/auth/sso/callback", data=b"assertion=bogus", method="POST")
+    try:
+        code = urllib.request.urlopen(req, timeout=20).status
+    except urllib.error.HTTPError as e:
+        code = e.code
+    if code >= 500:
+        raise RuntimeError(f"SSO callback misbehaves: {code}")
+    log(f"SSO_SMOKE=ok (bogus assertion -> {code}, no 5xx)")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--publish-agent", action="store_true")
+    ap.add_argument("--version", required=True)
+    a = ap.parse_args()
+    if not PASSWORD:
+        log("GTI_SSH_PASSWORD not provided")
+        return 2
+    version = a.version
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    bdir = f"/home/administrador/backups/gti-fiscal-deploy-{stamp}"
+    tar_local = REPO / "dist" / f"deploy_{stamp}.tar"
+    tar_local.parent.mkdir(exist_ok=True)
+    subprocess.run(["git", "archive", "--format=tar", "-o", str(tar_local), "HEAD"], check=True, cwd=REPO)
+    installer = REPO / "dist" / "installer" / f"GTIFiscalAgent-Setup-{version}.exe"
+    if a.publish_agent and not installer.exists():
+        log(f"installer not found: {installer}")
+        return 2
+
+    r = Remote(a.dry_run)
+    touched = False
+    st = {"stage": "connect"}
+    try:
+        st["stage"] = "preflight"
+        r.run("echo SSH_OK; docker ps --format '{{.Names}}' | grep -c gti-fiscal-hub", mutating=False)
+        free = r.run(f"df -Pm {REMOTE} | tail -1 | awk '{{print $4}}'", mutating=False).split()
+        if free and free[0].isdigit() and int(free[0]) < 2000:
+            raise RuntimeError(f"remote disk too low: {free[0]} MB free")
+        r.run(f"docker exec {HUB} python -c \"import urllib.request as u;print(u.urlopen('http://localhost:8000/version').read().decode())\"", check=False, mutating=False)
+        st["stage"] = "backup"
+        # 4. backup: DB + release storage + env/config + previous tree. Failure aborts before anything changes.
+        r.run(f"mkdir -p {bdir}")
+        r.run(f"docker exec {PG} pg_dump -U gti -d gti_fiscal -Fc > {bdir}/gti_fiscal.dump && test -s {bdir}/gti_fiscal.dump")
+        r.run(f"docker exec {HUB} tar -C /app/data -cz releases > {bdir}/releases.tgz && test -s {bdir}/releases.tgz")
+        r.run(f"cp {COMPOSE_DIR}/.env {bdir}/hub.env && chmod 600 {bdir}/hub.env")
+        r.run(f"tar -czf {bdir}/previous_tree.tgz -C {REMOTE} --exclude=./deploy/hub/backups . && test -s {bdir}/previous_tree.tgz")
+        log(f"BACKUP_DIR={bdir}")
+        # 5. transfer (git archive never contains .env / secrets; .env.local is gitignored)
+        st["stage"] = "upload"
+        r.put(tar_local, "/tmp/gti_fiscal_deploy.tar")
+        touched = True
+        st["stage"] = "extract"
+        r.run(f"tar -xf /tmp/gti_fiscal_deploy.tar -C {REMOTE} && rm -f /tmp/gti_fiscal_deploy.tar")
+        r.run(f"sed -i 's/^GTI_FISCAL_VERSION=.*/GTI_FISCAL_VERSION={version}/' {COMPOSE_DIR}/.env")
+        st["stage"] = "docker_build_up"
+        # 6/7. only the Hub is rebuilt; Postgres and the Gerenciador stack are untouched. Migrations run at start.
+        r.run(f"cd {COMPOSE_DIR} && {COMPOSE} build fiscal-hub && {COMPOSE} up -d fiscal-hub", timeout=900)
+        st["stage"] = "migration_head"
+        head = r.run(f"sleep 10; docker exec {HUB} python -m alembic -c central/alembic.ini current", check=False, mutating=False)
+        if not a.dry_run and "(head)" not in head:
+            raise RuntimeError("alembic is not at head after start")
+        st["stage"] = "health"
+        wait_health(r, version)
+        # 9. Agent release (immutable: publish_agent_release refuses a different sha256 for an existing version)
+        if a.publish_agent:
+            st["stage"] = "publish_release"
+            digest = hashlib.sha256(installer.read_bytes()).hexdigest()
+            r.put(installer, f"/tmp/{installer.name}")
+            r.run(f"docker cp /tmp/{installer.name} {HUB}:/tmp/ && rm -f /tmp/{installer.name}")
+            r.run(f"docker exec {HUB} python central/scripts/publish_agent_release.py --artifact /tmp/{installer.name} --version {version}")
+            r.run(f"docker exec {HUB} python -c \"from central.app.db import engine; from sqlalchemy import text; "
+                  f"print(engine.connect().execute(text(\\\"select version,status,size_bytes,sha256 from agent_releases where version='{version}'\\\")).fetchall())\"",
+                  check=False)
+            log(f"EXPECTED_SHA256={digest} SIZE={installer.stat().st_size}")
+            # older Setup installers stop being offered (never deleted); the newest PUBLISHED release is the default
+            r.run(f"docker exec {HUB} python -c \"from central.app.db import engine; from sqlalchemy import text; from sqlalchemy.orm import Session; "
+                  f"s=Session(engine); n=s.execute(text(\\\"update agent_releases set status='REVOKED' where status='PUBLISHED' and filename like 'GTIFiscalAgent-Setup-%.exe' and version<>'{version}'\\\")).rowcount; s.commit(); print('revoked', n)\"",
+                  check=False)
+            st["stage"] = "verify_download"
+            r.run(f"docker exec {HUB} python central/scripts/verify_release_download.py {version}")
+        else:
+            log("RELEASE_PUBLISH=skipped")
+        if not a.dry_run:
+            st["stage"] = "public_smoke"
+            public_smoke(version)
+            try:  # Gerenciador/SSO reachability is reported, never a reason to roll a healthy Hub back
+                public_extra()
+            except Exception as exc:  # noqa: BLE001
+                log(f"WARN extra smoke: {exc}")
+        st["stage"] = "done"
+        write_result("OK", "", False)
+        log("ROLLBACK_REQUIRED=false")
+        log("DEPLOY_OK" if not a.dry_run else "DRY_RUN_OK")
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        log(f"FAILED_STAGE={st['stage']}")
+        log(f"REMOTE_ERROR={exc}")
+        log(f"DEPLOY_FAILED: {exc}")
+        write_result("FAILED", f"{st['stage']}: {exc}", touched and not a.dry_run)
+        if touched and not a.dry_run:
+            log("ROLLBACK_REQUIRED=true — restoring previous tree (Postgres volume is NOT touched)")
+            try:
+                r.run(f"tar -xzf {bdir}/previous_tree.tgz -C {REMOTE} --no-same-owner -m --exclude=./deploy/hub/backups")
+                r.run(f"cd {COMPOSE_DIR} && {COMPOSE} build fiscal-hub && {COMPOSE} up -d fiscal-hub", timeout=900)
+                log(f"ROLLBACK_APPLIED. DB dump kept at {bdir}/gti_fiscal.dump (restore manually only if a migration ran)")
+            except Exception as rb:  # noqa: BLE001
+                log(f"ROLLBACK_FAILED: {rb}. Backup at {bdir}")
+        else:
+            log("ROLLBACK_REQUIRED=false (production untouched)")
+        return 1
+    finally:
+        tar_local.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fiscal/scripts/discover_erp_schema.py

@@ -0,0 +1,33 @@
+"""Read-only Firebird schema/context discovery (no DML/DDL). Writes JSON to stdout."""
+import json, os, re, sys
+from pathlib import Path
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+from gti_fiscal_agent.firebird_reader import _connect  # noqa: E402
+for l in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+    if "=" in l and not l.startswith("#"):
+        k, _, v = l.partition("="); os.environ.setdefault(k.strip(), v.strip())
+KW = re.compile(r"CFOP|CST|CSOSN|ORIGEM|PIS|COFINS|CEST|IPI|MVA|FCP|CLASSTRIB|IBS|CBS|NCM|ICMS|IVA|MARGEM|ALIQ|NATUREZA|CRT|REGIME|TRIB|PERC|BASE_", re.I)
+conn = _connect(os.environ); cur = conn.cursor()
+cur.execute("select trim(RDB$RELATION_NAME), case when RDB$VIEW_SOURCE is null then 0 else 1 end from RDB$RELATIONS where coalesce(RDB$SYSTEM_FLAG,0)=0")
+rels = cur.fetchall()
+cur.execute("select trim(rf.RDB$RELATION_NAME), trim(rf.RDB$FIELD_NAME), f.RDB$FIELD_TYPE, coalesce(f.RDB$CHARACTER_LENGTH,f.RDB$FIELD_LENGTH), f.RDB$FIELD_SCALE from RDB$RELATION_FIELDS rf join RDB$FIELDS f on f.RDB$FIELD_NAME=rf.RDB$FIELD_SOURCE where coalesce(rf.RDB$SYSTEM_FLAG,0)=0")
+cols = {}
+for t, c, ty, ln, sc in cur.fetchall():
+    cols.setdefault(t, []).append((c, ty, ln, sc))
+out = {"tables": {}}
+for t, isview in rels:
+    try:
+        cur.execute(f'select count(*) from "{t}"'); n = cur.fetchone()[0]
+    except Exception as e:
+        n = None
+    fc = [c for c in cols.get(t, []) if KW.search(c[0])]
+    out["tables"][t] = {"rows": n, "view": bool(isview), "ncols": len(cols.get(t, [])), "fiscal_cols": [c[0] for c in fc]}
+cur.execute("select trim(RDB$PROCEDURE_NAME) from RDB$PROCEDURES where coalesce(RDB$SYSTEM_FLAG,0)=0"); out["procedures"] = [r[0] for r in cur.fetchall()]
+cur.execute("select trim(RDB$TRIGGER_NAME), trim(RDB$RELATION_NAME) from RDB$TRIGGERS where coalesce(RDB$SYSTEM_FLAG,0)=0"); out["triggers"] = [list(r) for r in cur.fetchall()]
+cur.execute("""select trim(rc.RDB$RELATION_NAME), trim(s.RDB$FIELD_NAME), trim(rc2.RDB$RELATION_NAME) from RDB$RELATION_CONSTRAINTS rc
+ join RDB$REF_CONSTRAINTS r on r.RDB$CONSTRAINT_NAME=rc.RDB$CONSTRAINT_NAME join RDB$RELATION_CONSTRAINTS rc2 on rc2.RDB$CONSTRAINT_NAME=r.RDB$CONST_NAME_UQ
+ join RDB$INDEX_SEGMENTS s on s.RDB$INDEX_NAME=rc.RDB$INDEX_NAME where rc.RDB$CONSTRAINT_TYPE='FOREIGN KEY'""")
+out["fks"] = [list(r) for r in cur.fetchall()]
+conn.close()
+print(json.dumps(out, ensure_ascii=False))

fiscal/scripts/discover_inbound_fiscal_evidence.py

@@ -0,0 +1,114 @@
+"""Discover inbound fiscal evidence from SGV databases using SELECT-only access."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Iterable
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SENSITIVE = re.compile(r"CNPJ|CPF|XML|CHAVE|RAZAO|NOME|ENDERECO|FONE|EMAIL", re.I)
+TOKEN_GROUPS = {
+    "HEADER": {"NOTA", "NF", "DOCUMENTO", "CABECALHO", "EMISSAO", "SERIE"},
+    "ITEM": {"ITEM", "CODPRODUTO", "CODIGO", "QTD", "QUANTIDADE", "VALOR"},
+    "SUPPLIER": {"FORNEC", "EMITENTE", "CNPJ", "CPF", "RAZAO"},
+    "KEY": {"CHAVE", "NFE", "NFCE", "ACCESS", "PROTOCOLO"},
+    "FISCAL_ITEM": {"NCM", "CFOP", "CST", "CSOSN", "CEST", "ORIG", "ICMS", "PIS", "COFINS", "IPI", "MVA"},
+}
+
+
+def classify_evidence_source(table: str, columns: Iterable[str]) -> set[str]:
+    text = f"{table} {' '.join(columns)}".upper()
+    result = {category for category, tokens in TOKEN_GROUPS.items() if any(token in text for token in tokens)}
+    return result or {"UNKNOWN"}
+
+
+def discover_from_rows(column_rows: Iterable[tuple[Any, ...]], relationship_rows: Iterable[tuple[Any, ...]]) -> dict[str, Any]:
+    tables: dict[str, dict[str, Any]] = {}
+    for table, field, field_type, field_length in column_rows:
+        table = str(table).strip()
+        field = str(field).strip()
+        record = tables.setdefault(table, {"columns": [], "categories": [], "xml_or_blob": False})
+        if not SENSITIVE.search(field):
+            record["columns"].append(field)
+        if field_type == 261 or re.search(r"XML|BLOB|PAYLOAD|DOCUMENT", field, re.I):
+            record["xml_or_blob"] = True
+    for table, record in tables.items():
+        categories = classify_evidence_source(table, record["columns"])
+        record["categories"] = sorted(categories)
+    relationships = []
+    for from_table, from_field, to_table, to_field in relationship_rows:
+        relationships.append({"from_table": str(from_table).strip(), "from_field": str(from_field).strip(), "to_table": str(to_table).strip(), "to_field": str(to_field).strip()})
+    return {"tables": tables, "relationships": relationships}
+
+
+def safe_row_count(cursor: Any, table: str) -> dict[str, Any] | int:
+    try:
+        cursor.execute(f'SELECT COUNT(*) FROM "{table}"')
+        return int(cursor.fetchone()[0])
+    except Exception as exc:  # external tables can be blocked by server policy
+        return {"status": "ROW_COUNT_UNAVAILABLE", "error_type": type(exc).__name__}
+
+
+def _load_env() -> None:
+    path = ROOT / ".env"
+    if path.exists():
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if "=" in line and not line.lstrip().startswith("#"):
+                key, _, value = line.partition("=")
+                os.environ.setdefault(key.strip(), value.strip())
+
+
+def discover_database(path: Path) -> dict[str, Any]:
+    import fdb
+
+    conn = fdb.connect(
+        database=str(path),
+        user=os.environ["FB_USER"],
+        password=os.environ["FB_PASSWORD"],
+        fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+        isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO,
+    )
+    try:
+        cur = conn.cursor()
+        cur.execute("""SELECT TRIM(rf.RDB$RELATION_NAME), TRIM(rf.RDB$FIELD_NAME), f.RDB$FIELD_TYPE, COALESCE(f.RDB$CHARACTER_LENGTH, f.RDB$FIELD_LENGTH)
+                       FROM RDB$RELATION_FIELDS rf JOIN RDB$FIELDS f ON f.RDB$FIELD_NAME = rf.RDB$FIELD_SOURCE
+                       JOIN RDB$RELATIONS r ON r.RDB$RELATION_NAME = rf.RDB$RELATION_NAME
+                       WHERE COALESCE(r.RDB$SYSTEM_FLAG, 0) = 0""")
+        columns = cur.fetchall()
+        cur.execute("""SELECT TRIM(rc.RDB$RELATION_NAME), TRIM(s.RDB$FIELD_NAME), TRIM(rc2.RDB$RELATION_NAME), TRIM(s2.RDB$FIELD_NAME)
+                       FROM RDB$RELATION_CONSTRAINTS rc
+                       JOIN RDB$INDEX_SEGMENTS s ON s.RDB$INDEX_NAME = rc.RDB$INDEX_NAME
+                       JOIN RDB$REF_CONSTRAINTS ref ON ref.RDB$CONSTRAINT_NAME = rc.RDB$CONSTRAINT_NAME
+                       JOIN RDB$RELATION_CONSTRAINTS rc2 ON rc2.RDB$CONSTRAINT_NAME = ref.RDB$CONST_NAME_UQ
+                       JOIN RDB$INDEX_SEGMENTS s2 ON s2.RDB$INDEX_NAME = rc2.RDB$INDEX_NAME
+                       WHERE rc.RDB$CONSTRAINT_TYPE = 'FOREIGN KEY'""")
+        relationships = cur.fetchall()
+        result = discover_from_rows(columns, relationships)
+        for table, record in result["tables"].items():
+            record["row_count"] = safe_row_count(cur, table)
+        result.update({"database": path.name, "mode": "READ_ONLY", "firebird_writes": 0, "xml_documents_available": any(r["xml_or_blob"] for r in result["tables"].values())})
+        return result
+    finally:
+        conn.close()
+
+
+def main() -> None:
+    _load_env()
+    paths = [ROOT / "TESTESOFICIAIS.FDB"] + sorted((ROOT / "Banco").glob("*.FDB"))
+    output = {"artifact": "ERP_INBOUND_FISCAL_EVIDENCE_MAP_V1", "mode": "READ_ONLY", "databases": [], "firebird_writes": 0}
+    for path in paths:
+        try:
+            output["databases"].append(discover_database(path))
+        except Exception as exc:  # record unavailable evidence without guessing
+            output["databases"].append({"database": path.name, "mode": "READ_ONLY", "status": "UNAVAILABLE", "error_type": type(exc).__name__, "firebird_writes": 0})
+    destination = ROOT / "docs" / "ERP_INBOUND_FISCAL_EVIDENCE_MAP_V1.json"
+    destination.write_text(json.dumps(output, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"artifact": output["artifact"], "databases": len(output["databases"]), "firebird_writes": 0}))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/discover_testesoficiais_fiscal.py

@@ -0,0 +1,168 @@
+"""READ-ONLY discovery of fiscal/RTC/PIS/COFINS fields in TESTESOFICIAIS.FDB (and only that database).
+
+    python scripts/discover_testesoficiais_fiscal.py [--json out.json]
+
+Credentials come from the process environment (FB_USER / FB_PASSWORD, optional FIREBIRD_CLIENT_LIBRARY) or the
+local ignored .env - never from the command line, never printed. The connection uses READ COMMITTED READ ONLY
+isolation and every statement goes through a guard that only lets SELECT reach the driver.
+"""
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DATABASE = ROOT / "TESTESOFICIAIS.FDB"  # fixed on purpose: this script audits no other database
+
+KEYWORDS = ("TRIB", "IBS", "CBS", "PIS", "COFINS", "CRED", "REFORMA", "RTC", "CLASS")
+FISCAL_HINTS = ("TRIB", "CST", "CFOP", "NCM", "PIS", "COF", "IBS", "CBS", "CRED", "ALIQ", "ICMS", "IPI", "CEST", "CSOSN", "CLASS", "ORIG", "REFORMA", "RTC", "SIT_T")
+_TYPES = {7: "SMALLINT", 8: "INTEGER", 16: "BIGINT", 10: "FLOAT", 27: "DOUBLE", 12: "DATE", 13: "TIME", 35: "TIMESTAMP", 14: "CHAR", 37: "VARCHAR", 261: "BLOB"}
+
+
+class ReadOnlyCursor:
+    """Only SELECT statements are ever handed to the driver; anything else is counted and refused."""
+    write_attempts = 0
+    write_successes = 0
+
+    def __init__(self, cursor):
+        self._cursor = cursor
+
+    def execute(self, sql, params=()):
+        if not re.match(r"^\s*select\b", sql, re.IGNORECASE):
+            ReadOnlyCursor.write_attempts += 1
+            raise RuntimeError("non-SELECT statement refused")
+        return self._cursor.execute(sql, params) if params else self._cursor.execute(sql)
+
+    def fetchall(self):
+        return self._cursor.fetchall()
+
+    def fetchone(self):
+        return self._cursor.fetchone()
+
+
+def load_env():
+    env_file = ROOT / ".env"
+    if env_file.exists():
+        for line in env_file.read_text(encoding="utf-8").splitlines():
+            if "=" in line and not line.startswith("#"):
+                key, _, value = line.partition("=")
+                os.environ.setdefault(key.strip(), value.strip())
+
+
+def classify(table, column):
+    """Name-based first pass only. It is never taken as proof of meaning: the report lists evidence and a human/agent decides."""
+    name = column.upper()
+    if re.search(r"CCLASSTRIB|CLASS_?TRIB|CLASSIFICACAO_TRIBUTARIA", name):
+        return "CONFIRMED_MATCH", "cClassTrib"
+    if re.search(r"CST_?(IBS|CBS)|(IBS|CBS)_?CST|CSTIBSCBS|CST_IBSCBS", name):
+        return "CONFIRMED_MATCH", "CST IBS/CBS"
+    if re.search(r"(^|_)(IBS|CBS)($|_)|IBS|CBS", name) and not re.search(r"CBSA", name):
+        return "CONFIRMED_MATCH", "IBS/CBS"
+    if re.search(r"CCREDPRES|CRED_?PRES", name):
+        return "CONFIRMED_MATCH", "crédito presumido"
+    if re.search(r"(^|_)PIS($|_)|_PIS|PIS_|COD_(ENTRADA|SAIDA)_PIS", name):
+        return "CONFIRMED_MATCH", "PIS"
+    if re.search(r"COFINS", name):
+        return "CONFIRMED_MATCH", "COFINS"
+    if re.search(r"REFORMA|(^|_)RTC($|_)", name):
+        return "POSSIBLE_MATCH", "reforma/RTC (nome)"
+    if re.search(r"TRIB", name):
+        return "POSSIBLE_MATCH", "tributação (nome genérico)"
+    if re.search(r"CRED", name):
+        return "POSSIBLE_MATCH", "crédito (nome genérico)"
+    if re.search(r"CLASS", name):
+        return "POSSIBLE_MATCH", "classificação (nome genérico)"
+    return "UNRELATED", ""
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--json", default=None)
+    args = parser.parse_args()
+    load_env()
+    sys.path.insert(0, str(ROOT / "agent" / "src"))
+    import fdb
+
+    conn = fdb.connect(database=str(DATABASE), user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"],
+                       fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"), isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+    cur = ReadOnlyCursor(conn.cursor())
+    result = {"database": DATABASE.name, "mode": "READ_ONLY", "firebird_server_version": getattr(conn, "server_version", None),
+              "ods": f"{getattr(conn, 'ods_version', '?')}.{getattr(conn, 'ods_minor_version', '?')}"}
+    cur.execute("""SELECT TRIM(rf.RDB$RELATION_NAME), TRIM(rf.RDB$FIELD_NAME), f.RDB$FIELD_TYPE, COALESCE(f.RDB$CHARACTER_LENGTH, f.RDB$FIELD_LENGTH),
+                          f.RDB$FIELD_SCALE, rf.RDB$NULL_FLAG, TRIM(rf.RDB$FIELD_SOURCE), rf.RDB$DEFAULT_SOURCE, f.RDB$DEFAULT_SOURCE, rf.RDB$FIELD_POSITION
+                   FROM RDB$RELATION_FIELDS rf JOIN RDB$FIELDS f ON f.RDB$FIELD_NAME = rf.RDB$FIELD_SOURCE
+                   JOIN RDB$RELATIONS r ON r.RDB$RELATION_NAME = rf.RDB$RELATION_NAME
+                   WHERE COALESCE(r.RDB$SYSTEM_FLAG, 0) = 0 AND r.RDB$VIEW_BLR IS NULL""")
+    columns = []
+    for table, column, ftype, length, scale, null_flag, source, rf_default, f_default, position in cur.fetchall():
+        default = rf_default or f_default
+        default = str(default.read() if hasattr(default, "read") else default).replace("DEFAULT", "").strip() if default else None
+        columns.append({"table": table, "column": column, "type": _TYPES.get(ftype, f"type{ftype}") + (f"(scale {scale})" if scale else ""), "length": length,
+                        "nullable": not bool(null_flag), "default": default, "domain": None if source.startswith("RDB$") else source, "position": position})
+    result["tables"] = len({c["table"] for c in columns})
+    result["total_columns"] = len(columns)
+
+    c25 = [c for c in columns if c["table"] == "C000025"]
+    result["c000025_columns"] = [c["column"] for c in sorted(c25, key=lambda c: c["position"])]
+    result["c000025_fiscal_columns"] = [c for c in sorted(c25, key=lambda c: c["position"]) if any(h in c["column"].upper() for h in FISCAL_HINTS)]
+
+    matches = []
+    for column in columns:
+        verdict, concept = classify(column["table"], column["column"])
+        if verdict != "UNRELATED":
+            matches.append({**column, "classification": verdict, "concept": concept})
+    result["matches"] = matches
+
+    def stats(table, column):
+        cur.execute(f'SELECT COUNT(*), COUNT("{column}"), COUNT(DISTINCT "{column}") FROM "{table}"')
+        total, non_null, distinct = cur.fetchone()
+        info = {"rows": total, "non_null": non_null, "distinct": distinct}
+        cur.execute(f'SELECT FIRST 6 "{column}", COUNT(*) FROM "{table}" WHERE "{column}" IS NOT NULL GROUP BY "{column}" ORDER BY 2 DESC')
+        info["top_values"] = [[str(v).strip()[:24] if v is not None else None, n] for v, n in cur.fetchall()]
+        return info
+
+    for match in matches:
+        if match["type"].startswith(("BLOB",)):
+            continue
+        try:
+            match["usage"] = stats(match["table"], match["column"])
+        except Exception as error:  # noqa: BLE001 - reported, never fatal
+            match["usage"] = {"error": type(error).__name__}
+    for column in result["c000025_fiscal_columns"]:
+        column["classification"], column["concept"] = classify("C000025", column["column"])
+        try:
+            column["usage"] = stats("C000025", column["column"])
+            cur.execute(f"""SELECT COUNT(*) FROM "C000025" WHERE TRIM(COALESCE(CAST("{column["column"]}" AS VARCHAR(40)), '')) NOT IN ('', '0', '0.00', '0,00')""")
+            column["usage"]["meaningful_non_empty"] = cur.fetchone()[0]
+        except Exception as error:  # noqa: BLE001
+            column["usage"] = {"error": type(error).__name__}
+    # tables that are entirely about the reform (name based), with their full column list and a few rows' worth of values
+    rtc_tables = sorted({c["table"] for c in columns if re.search(r"RTC|IBS|CBS|REFORMA|CLASSTRIB", c["table"].upper())})
+    result["rtc_tables"] = {}
+    for table in rtc_tables:
+        cols = [c for c in columns if c["table"] == table]
+        cur.execute(f'SELECT COUNT(*) FROM "{table}"')
+        result["rtc_tables"][table] = {"rows": cur.fetchone()[0], "columns": [(c["column"], c["type"], c["length"]) for c in sorted(cols, key=lambda c: c["position"])]}
+        if table == "RTC_CST":
+            cur.execute('SELECT FIRST 20 * FROM "RTC_CST"')
+            result["rtc_tables"][table]["sample"] = [[str(v).strip()[:60] for v in row] for row in cur.fetchall()]
+    cur.execute('SELECT USAR_REFORMA_TRIBUTARIA FROM PARAMETROS')
+    result["parametros_usar_reforma_tributaria"] = [str(v[0]) for v in cur.fetchall()]
+    cur.execute('SELECT COUNT(*) FROM C000025')
+    result["c000025_rows"] = cur.fetchone()[0]
+    # how many products carry a CCLASSTRIB that exists in the RTC_CCLASSTRIB catalog (orphan check, no inference)
+    cur.execute("""SELECT COUNT(*) FROM C000025 p WHERE TRIM(COALESCE(p.CCLASSTRIB, '')) <> '' AND EXISTS (SELECT 1 FROM RTC_CCLASSTRIB c WHERE c.CCLASSTRIB = p.CCLASSTRIB)""")
+    result["c000025_cclasstrib_in_catalog"] = cur.fetchone()[0]
+    result["write_attempts"] = ReadOnlyCursor.write_attempts
+    result["write_successes"] = ReadOnlyCursor.write_successes
+    conn.close()
+    text = json.dumps(result, ensure_ascii=False, indent=1, default=str)
+    if args.json:
+        Path(args.json).write_text(text, encoding="utf-8")
+    print(f"tables={result['tables']} columns={result['total_columns']} matches={len(matches)} writes_attempted={result['write_attempts']}")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/dry_run_universe.py

@@ -0,0 +1,66 @@
+"""Missão 2 / Bloco 1 — dry-run fiscal read-only sobre um banco arbitrário (Agent 2 = GTI.FDB incluso).
+
+Reaproveita o motor puro (central.app.field_contract) e as funções analyze()/summarize()
+já existentes em scripts/local_completion.py (mesma taxonomia ALREADY_CORRECT/CHANGE_REQUIRED/
+NOT_APPLICABLE/MANUAL_INPUT_REQUIRED). NUNCA chama apply()/execute_guarded_product_update —
+este script não importa firebird_write_executor e não abre conexão rw=True em nenhum ponto.
+
+    python scripts/dry_run_universe.py --name GTI --path "D:\\PROJETOS\\GTISISTEMAS\\Banco\\GTI.FDB" [--company-code C] [--crt-source AUTO|EMISSOR|C000004]
+"""
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+import run_fiscal_decision_v1 as base  # noqa: E402
+import local_completion as lc  # noqa: E402
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--name", required=True)
+    ap.add_argument("--path", required=True)
+    ap.add_argument("--company-code")
+    ap.add_argument("--crt-source")
+    ap.add_argument("--out")
+    a = ap.parse_args()
+    base.load_dotenv(ROOT / ".env")
+    token = os.environ["AGENT_DEV_TOKEN"]
+    if a.company_code or a.crt_source:
+        lc.COMPANY_CFG[a.name] = {k: v for k, v in (("company_code", a.company_code), ("crt_source", a.crt_source)) if v}
+    an = lc.analyze(a.name, a.path, token)
+    summary = lc.summarize(an)
+    from collections import Counter
+    scope_by_key = Counter()
+    for res in an["results"].values():
+        for fld, r in res.items():
+            if fld.startswith("_"):
+                continue
+            if r.get("state") == "MANUAL_INPUT_REQUIRED":
+                scope_by_key[(fld, r.get("input_key"), r.get("input_scope"))] += 1
+    summary["manual_inputs_by_scope"] = {f"{f}|{k}|{s}": n for (f, k, s), n in sorted(scope_by_key.items(), key=lambda x: -x[1])}
+    out_path = Path(a.out) if a.out else (ROOT / "docs" / "runs" / f"{a.name}_dryrun_universe_summary.json")
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(summary, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    print(json.dumps({"name": a.name, "total_products": summary["total_products"], "company": summary["company"],
+                       "change_required_cells": summary["change_required_cells"], "write_eligible_cells": summary["write_eligible_cells"]}, indent=1, default=str))
+    ndjson_path = ROOT / "docs" / "runs" / f"{a.name}_dryrun_universe.ndjson.gz"
+    import gzip
+    with gzip.open(ndjson_path, "wt", encoding="utf-8") as f:
+        from central.app.field_contract import WRITE_FIELDS, CONTRACT_VERSION
+        for p in an["products"]:
+            code = p["_rk"]; res = an["results"][code]
+            for fld in WRITE_FIELDS:
+                r = res[fld]
+                f.write(json.dumps({"db": a.name, "codigo": p["CODIGO"], "produto": p["PRODUTO"], "field": fld, "current": r["current"], "proposed": r["proposed"],
+                                     "status": r["state"], "reason": r["reason"], "input_key": r.get("input_key"),
+                                     "provenance": f"{CONTRACT_VERSION}|" + ",".join(f"{k}:{v}" for k, v in res["_ds"].items()) + f"|role={res['_facts']['role']}"}, ensure_ascii=False, default=str) + "\n")
+    print(f"summary -> {out_path}")
+    print(f"cells   -> {ndjson_path}")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/e2e_local_hub.py

@@ -0,0 +1,103 @@
+"""Local E2E hub for Phase D — Windows installer against a real HTTP Hub.
+
+Boots the control plane against a scratch SQLite DB, seeds a tenant + admin,
+publishes the real built EXE as release 1.1.1, creates a PENDING enrollment,
+generates an install code, then serves uvicorn on 127.0.0.1:PORT.
+
+The operator/Setup CLI then runs against this local Hub. Usage:
+
+    python scripts/e2e_local_hub.py --port 8901 --exe dist/installer/GTIFiscalAgent-Setup-1.1.1.exe
+"""
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import os
+import sys
+import tempfile
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT / "central"))
+
+from central.app import config, enrollment  # noqa: E402
+from central.app.models import AgentEnrollment, Tenant  # noqa: E402
+from central.scripts.publish_agent_release import publish  # noqa: E402
+from central.tests.test_control_plane import create_admin, seed  # noqa: E402
+from sqlalchemy import select
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--exe", default=str(ROOT / "dist/installer/GTIFiscalAgent-Setup-1.1.1.exe"))
+    args = parser.parse_args()
+
+    workdir = Path(tempfile.mkdtemp(prefix="gti_e2e_hub_"))
+    print(f"[e2e] workdir={workdir}")
+
+    replaced = dataclasses.replace(
+        config.settings,
+        agent_release_storage_path=str(workdir / "releases"),
+        base_url=f"http://127.0.0.1:{args.port}",
+        web_cookie_secure=False,
+    )
+    config.settings = replaced
+    if "app.config" in sys.modules:
+        sys.modules["app.config"].settings = replaced
+
+    url = f"sqlite:///{workdir / 'e2e_hub.db'}"
+    os.environ["DATABASE_URL"] = url
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import sessionmaker
+    from sqlalchemy.pool import StaticPool
+
+    from central.app.models import Base
+
+    engine = create_engine(url, connect_args={"check_same_thread": False}, poolclass=StaticPool)
+    Base.metadata.create_all(engine)
+    factory = sessionmaker(bind=engine, expire_on_commit=False)
+
+    seed(factory)
+
+    with factory() as session:
+        data = Path(args.exe)
+        if not data.exists():
+            print(f"[e2e] EXE artefact not found: {data}", file=sys.stderr)
+            return 2
+        release, _created = publish(session, data, version="1.1.1")
+        release_id = release.id
+        print(f"[e2e] published release {release.version} id={release_id}")
+
+        tenant = session.scalars(select(Tenant).limit(1)).first()
+        enr = AgentEnrollment(enrollment_uuid=str(uuid.uuid4()), tenant_id=tenant.id,
+                              display_name="Servidor E2E LOCAL", release_id=release_id, status="PENDING")
+        session.add(enr)
+        session.flush()
+
+        code = enrollment.generate_install_code()
+        enr.install_code_hash = enrollment.install_code_digest(code)
+        enr.install_code_expires_at = datetime.now(timezone.utc) + timedelta(seconds=86400)
+        enr.install_code_created_at = datetime.now(timezone.utc)
+        session.commit()
+        print(f"[e2e] enrollment_uuid={enr.enrollment_uuid}", flush=True)
+        print(f"[e2e] INSTALL_CODE={code}", flush=True)
+        (workdir / "install_code.txt").write_text(code)
+        (workdir / "enrollment_uuid.txt").write_text(enr.enrollment_uuid)
+        print(f"[e2e] workdir={workdir}", flush=True)
+
+    import uvicorn
+
+    from central.app.main import create_app
+
+    app = create_app(database_probe=lambda: True, session_factory=factory, bootstrap_token=None)
+    print(f"[e2e] serving hub on http://127.0.0.1:{args.port}")
+    uvicorn.run(app, host="127.0.0.1", port=args.port, log_level="info")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fiscal/scripts/e2e_zero_touch_local.py

@@ -0,0 +1,83 @@
+"""Real zero-touch runtime E2E against the local dev Hub + a real Firebird test database.
+
+No manual step between heartbeat and result: a brand-new installation identity sends its
+first heartbeat, the Hub queues exactly one INITIAL_SYNC, the Agent claims and executes it
+(READ-ONLY), coverage/blockers land on the Hub; then the central scheduler queues a
+SYNC_INCREMENTAL by itself (interval shortened to 1 s for the test) which must reprocess
+only the delta (nothing changed -> 0), and finally a central pause stops job execution while
+heartbeats continue.
+
+Usage (dev Hub on :8000, .env with FB credentials):  python scripts/e2e_zero_touch_local.py
+"""
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path[:0] = [str(ROOT), str(ROOT / "agent" / "src"), str(ROOT / "agent" / "scripts")]
+
+from dotenv import dotenv_values  # noqa: E402
+
+env_file = dotenv_values(ROOT / ".env")
+HUB = "http://localhost:8000"
+
+
+def psql(sql):
+    out = subprocess.run(["docker", "exec", "projeto-postgres-1", "psql", "-U", "gti", "-d", "gti_fiscal", "-At", "-F", "|", "-c", sql], capture_output=True, text=True)
+    return out.stdout.strip()
+
+
+def main():
+    import run_agent_service as service
+
+    tmp = Path(tempfile.mkdtemp(prefix="gti_zt_"))
+    # A brand-new Agent (own tenant + token), like a freshly enrolled installation — never the shared dev agent.
+    reg = subprocess.run(["docker", "exec", "projeto-fiscal-hub-1", "python", "central/scripts/register_agent.py", "--company", f"e2e-zero-touch-{int(time.time())}", "--name", "zt"], capture_output=True, text=True).stdout
+    token = next(line.split("=", 1)[1] for line in reg.splitlines() if line.strip().startswith("AGENT_TOKEN="))
+    installation = str(uuid.uuid4())
+    os.environ.update({
+        "GTI_HUB_URL": HUB, "AGENT_TOKEN": token, "AGENT_ID": "dev", "INSTALLATION_ID": installation,
+        "FIREBIRD_DATABASE_PATH": env_file["FIREBIRD_DATABASE_PATH"], "FB_USER": env_file.get("FB_USER", "SYSDBA"), "FB_PASSWORD": env_file["FB_PASSWORD"],
+        "FIREBIRD_CLIENT_LIBRARY": env_file.get("FIREBIRD_CLIENT_LIBRARY", ""), "FIREBIRD_WRITES": "0", "FISCAL_MODE": "DRY_RUN",
+        "AGENT_STATE_DB": str(tmp / "state.sqlite"), "AGENT_LOG_PATH": str(tmp / "agent.log"), "POLL_INTERVAL_SECONDS": "0.2",
+        "AGENT_JOBS_ENABLED": "0",  # legacy local toggle deliberately set to 0: must be ignored (control is central)
+    })
+    config = service.Config(os.environ)
+    service.setup_logging(config.log_path)
+    print("INSTALLATION_ID=", installation, "FIREBIRD_WRITES=", config.firebird_writes)
+
+    def run(n):
+        service.run(config, os.environ, max_iterations=n)
+
+    # 1) first heartbeat -> INITIAL_SYNC by the Hub -> claimed + executed in the same loop
+    run(4)
+    jobs = psql(f"select j.id,j.kind,j.status,j.result_summary->>'products_total',j.result_summary->>'products_changed' from jobs j join installations i on i.agent_id=j.agent_id where i.installation_id='{installation}' order by j.id")
+    print("AFTER_INITIAL:\n" + jobs)
+    snap = psql(f"select s.total_products,s.fiscally_complete,s.safe_blocked,s.failed_products,s.blockers from agent_snapshots s join installations i on i.id=s.installation_id where i.installation_id='{installation}'")
+    print("SNAPSHOT=", snap)
+    blockers = psql(f"select count(*) from blocked_products b join installations i on i.id=b.installation_id where i.installation_id='{installation}'")
+    print("BLOCKERS_TOTAL=", blockers)
+
+    # 2) central scheduler: shorten the interval, next heartbeat queues one SYNC_INCREMENTAL by itself
+    psql(f"update installations set sync_interval_seconds=1 where installation_id='{installation}'")
+    time.sleep(2)
+    run(4)
+    print("AFTER_INCREMENTAL:\n" + psql(f"select j.id,j.kind,j.status,j.payload->>'reason',j.result_summary->>'products_total',j.result_summary->>'products_changed' from jobs j join installations i on i.agent_id=j.agent_id where i.installation_id='{installation}' order by j.id"))
+
+    # 3) central pause: heartbeat continues, nothing is claimed
+    psql(f"update installations set processing_enabled=false where installation_id='{installation}'")
+    before = psql("select count(*) from jobs where status='RUNNING'")
+    time.sleep(2)
+    run(3)
+    print("PAUSED_RUNNING_JOBS=", before, "LAST_STATUS=", psql(f"select last_status from installations where installation_id='{installation}'"))
+    print("WRITES:", psql(f"select coalesce(sum((result_summary->>'writes_attempted')::int),0), coalesce(sum((result_summary->>'writes_succeeded')::int),0) from jobs j join installations i on i.agent_id=j.agent_id where i.installation_id='{installation}'"))
+    print("LOCAL_ipi_write_log_rows=", __import__("sqlite3").connect(tmp / "state.sqlite").execute("select count(*), sum(write_status='DRY_RUN_ONLY') from ipi_write_log").fetchone())
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_acceptance_dev.py

@@ -0,0 +1,142 @@
+"""Acceptance rehearsal of the production scenario on DEV (real HTTP Hub + real Agent worker + Firebird COPY):
+
+  product WITHOUT EAN, NCM=00000000, cClassTrib typed by the operator -> visible status (no silent failure) -> an ADMIN decides the NCM of the conflicting GTIN in the KB ->
+  the flagged re-evaluation finds the unique verified product by NAME -> the Agent writes the NCM (typed write) -> read-back + audit -> second run writes 0.
+  Also: DRY_RUN shows the candidate without writing; EAN path (KB hit, zero provider requests) with latency; human override is preserved.
+
+    docker compose up -d --build fiscal-hub && python scripts/enrichment_acceptance_dev.py
+The ADMIN decision is applied through the same code as the panel route (kb.attest + mark_for_reevaluation), with operator name 'E2E-OPERATOR'. Writes go only to the disposable COPY.
+"""
+import json
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import enrichment_kb_e2e as ke  # noqa: E402
+import enrichment_local_hub_e2e as lh  # noqa: E402
+from gti_fiscal_agent.client import HubClient  # noqa: E402
+
+base, ce = ke.base, ke.ce
+GTIN = "7894900010015"
+
+
+def insert(code, name, ncm, ean, cclasstrib):
+    conn = base.connect(True); cur = conn.cursor()
+    cur.execute("INSERT INTO C000025 (CODIGO, PRODUTO, CODBARRA, CLASSIFICACAO_FISCAL, CCLASSTRIB) VALUES (?, ?, ?, ?, ?)", (code, name, ean, ncm, cclasstrib))
+    conn.commit(); conn.close()
+
+
+def row(code):
+    conn = base.connect(False); cur = conn.cursor()
+    cur.execute("SELECT CLASSIFICACAO_FISCAL, CEST, IPI, CCLASSTRIB, PRODUTO FROM C000025 WHERE CODIGO=?", (code,))
+    r = cur.fetchone(); conn.close()
+    return tuple(None if v is None else (v if isinstance(v, float) else str(v).strip()) for v in r) if r else None
+
+
+def ui(code, inst):
+    return lh.sql(f"select ui_status||'|'||coalesce(reason_code,'') from product_enrichments where product_code='{code}' and installation_id=(select id from installations where installation_id='{inst}')")
+
+
+def main():
+    checks, info = {}, {}
+    base.restore_copy()
+    c1 = HubClient(lh.HUB, lh.TOKEN)
+    inst = c1.identity()["installation_id"]
+    lh.set_features(inst, "DISABLED")
+    lh.sql(f"delete from product_field_audits where installation_id=(select id from installations where installation_id='{inst}')")
+    lh.sql(f"delete from product_enrichments where installation_id=(select id from installations where installation_id='{inst}')")
+    # start from the real situation: the KB has a CONFLICT for the Coca-Cola can (RINCAO x UNIAO), nothing verified
+    state = ke.exec_hub(f'''
+from sqlalchemy import select
+from central.app.db import SessionLocal
+from central.app.enrichment import kb
+from central.app.models import KbKnowledge, KbProduct
+with SessionLocal() as s:
+    p = s.scalar(select(KbProduct).where(KbProduct.gtin == "0{GTIN}"))
+    rows = s.scalars(select(KbKnowledge).where(KbKnowledge.kb_product_id == p.id, KbKnowledge.knowledge_key == "ncm")).all()
+    for r in rows:                                    # reset any earlier rehearsal: drop attestation
+        ev = dict(r.evidence or {{}}); fam = dict(ev.get("families") or {{}}); fam.pop("OPERATOR_ATTESTATION", None); ev["families"] = fam; r.evidence = ev; r.status = "OBSERVED"; r.validated_at = None
+    s.commit()
+    print("ROWS", sorted((r.value, r.status) for r in rows))
+''')
+    info["kb_before"] = state
+    w, stop = ke.worker_for(c1, "acc_dev")
+    lh.set_features(inst, "DRY_RUN"); w._features_at = -999; time.sleep(6)
+    # 1) DRY_RUN: product without EAN, placeholder NCM
+    insert("AC001", "COCA-COLA ORIGINAL LATA 350 ML", "00000000", None, "200004")
+    time.sleep(12)
+    info["status_before_decision"] = ui("AC001", inst)
+    checks["SILENT_FAILURE_FIXED_STATUS_VISIBLE"] = info["status_before_decision"].startswith("EAN_AUSENTE")
+    checks["NCM_UNCHANGED_UNTIL_DECISION"] = row("AC001")[0] == "00000000"
+    # 2) ADMIN decision in the KB (same code path as the panel route) -> flagged re-evaluation, still DRY_RUN
+    out = ke.exec_hub(f'''
+from central.app.db import SessionLocal
+from central.app.enrichment import history, kb, status
+from central.app.models import Installation
+from sqlalchemy import select
+with SessionLocal() as s:
+    cur = history.official_sets(s)
+    r = kb.attest(s, "0{GTIN}", "22021000", "E2E-OPERATOR", lambda v: v in cur, note="E2E rehearsal")
+    n = 0
+    for i in s.scalars(select(Installation).where(Installation.enrichment_mode != "DISABLED", Installation.features_configured.is_(True))):
+        n += status.mark_for_reevaluation(s, i.id)
+    s.commit()
+    print("ATTEST", r["status"], r["families"], "flagged", n)
+''')
+    info["attest"] = out
+    checks["ATTESTED_TO_VERIFIED_KB"] = "VERIFIED_KB" in out
+    t0 = time.monotonic()
+    while time.monotonic() - t0 < 40 and not ui("AC001", inst).startswith("SIMULADO"):
+        time.sleep(1)
+    info["status_dry_run_after_decision"] = ui("AC001", inst)
+    checks["DRY_RUN_SHOWS_CANDIDATE_ZERO_WRITES"] = ui("AC001", inst).startswith("SIMULADO") and row("AC001")[0] == "00000000"
+    # 3) AUTOMATIC: reevaluate (like the panel button) -> written by the Agent
+    lh.set_features(inst, "ENABLED"); w._features_at = -999; w._auth_cache = (None, 0.0); time.sleep(3)
+    lh.sql(f"update product_enrichments set reevaluate=true where product_code='AC001' and installation_id=(select id from installations where installation_id='{inst}')")
+    t0 = time.monotonic()
+    while time.monotonic() - t0 < 45 and row("AC001")[0] == "00000000":
+        time.sleep(0.5)
+    time.sleep(4)
+    r = row("AC001")
+    info["AC001_after"] = r
+    checks["NAME_ONLY_NCM_WRITTEN_BY_AGENT"] = r[0] == "22021000"
+    checks["CCLASSTRIB_PRESERVED"] = r[3] == "200004"
+    audit = lh.sql(f"select field||':'||coalesce(old_value,'')||'>'||coalesce(new_value,'')||':'||outcome||':'||coalesce(kb_status,'') from product_field_audits where product_code='AC001' and outcome='APPLIED' order by id")
+    info["audit"] = audit
+    checks["AUDIT_OLD_PLACEHOLDER_NEW_NCM"] = "CLASSIFICACAO_FISCAL:00000000>22021000:APPLIED" in audit
+    checks["FINAL_STATUS_ENRIQUECIDO"] = ui("AC001", inst).startswith("ENRIQUECIDO")
+    # 4) second run writes 0, zero provider requests
+    before_req, before_writes = ke.requests_total(), int(lh.sql("select count(*) from product_field_audits where outcome='APPLIED'"))
+    lh.sql(f"update product_enrichments set reevaluate=true where product_code='AC001' and installation_id=(select id from installations where installation_id='{inst}')")
+    time.sleep(25)
+    checks["SECOND_RUN_WRITES_0"] = int(lh.sql("select count(*) from product_field_audits where outcome='APPLIED'")) == before_writes and row("AC001")[0] == "22021000"
+    checks["ZERO_PROVIDER_REQUESTS_ON_KB_RESOLUTION"] = ke.requests_total() == before_req
+    # 5) EAN path on the now-verified GTIN: latency + zero provider requests
+    t0 = time.monotonic()
+    insert("AC002", "COCA-COLA ORIGINAL LATA 350 ML", "00000000", GTIN, "200004")
+    while time.monotonic() - t0 < 25 and row("AC002")[0] == "00000000":
+        time.sleep(0.2)
+    info["ean_latency_s"] = round(time.monotonic() - t0, 2)
+    checks["EAN_PATH_KB_HIT_WRITE"] = row("AC002")[0] == "22021000" and ke.requests_total() == before_req
+    # 6) real NCM preserved + human override preserved
+    insert("AC003", "COCA-COLA ORIGINAL LATA 350 ML", "19059090", GTIN, "200004"); time.sleep(10)
+    checks["EXISTING_REAL_NCM_PRESERVED"] = row("AC003")[0] == "19059090"
+    conn = base.connect(True); cur = conn.cursor(); cur.execute("UPDATE C000025 SET CLASSIFICACAO_FISCAL='19059090' WHERE CODIGO='AC001'"); conn.commit(); conn.close()
+    time.sleep(E_OVERRIDE_WAIT := 28)
+    lh.sql(f"update product_enrichments set reevaluate=true where product_code='AC001' and installation_id=(select id from installations where installation_id='{inst}')")
+    time.sleep(20)
+    checks["HUMAN_OVERRIDE_PRESERVED"] = row("AC001")[0] == "19059090"
+    stop.stop = True
+    result = {"dev_rehearsal": True, "info": info, "checks": checks, "ALL_PASS": all(checks.values())}
+    (ROOT / "docs" / "runs" / "enrichment_acceptance_dev.json").write_text(json.dumps(result, indent=1, default=str), encoding="utf-8")
+    print(json.dumps(result, indent=1, default=str))
+    sys.exit(0 if result["ALL_PASS"] else 1)
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_benchmark.py

@@ -0,0 +1,85 @@
+"""Conservative provider benchmark on REAL GTINs taken (read-only) from the lab ERP databases. Free quotas only, paced below documented limits.
+
+    python scripts/enrichment_benchmark.py --sample scratch_enrich/benchmark_gtins.json --out docs/PRODUCT_PROVIDER_BENCHMARK_V1.json [--limit 30]
+
+Each provider gets at most --limit lookups (UPCitemdb: also <= 12 per 30 s burst window; Open Food Facts: <= 12/min). Cosmos is measured only when COSMOS_TOKEN is set.
+Reports sample_size / found / not_found / description / brand / NCM / CEST / latency / error_rate per provider. Secrets are never printed.
+"""
+import argparse
+import json
+import os
+import statistics
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+import httpx  # noqa: E402
+
+from central.app.enrichment.providers import Cosmos, Oscbr, OpenBeautyFacts, OpenFoodFacts, OpenProductsFacts, ProviderError, UpcItemDb, USER_AGENT  # noqa: E402
+
+PACE = {"oscbr": 3.2, "upcitemdb": 2.6, "openfoodfacts": 5.2, "openproductsfacts": 5.2, "openbeautyfacts": 5.2, "cosmos": 1.0}      # seconds between calls: comfortably under the documented burst / per-minute limits
+
+
+def bench(provider, items):
+    out = {"provider": provider.name, "configured": provider.configured, "sample_size": 0, "found": 0, "not_found": 0, "with_description": 0, "with_brand": 0, "with_ncm": 0, "with_cest": 0, "errors": 0, "error_kinds": {}, "latencies_ms": [], "per_gtin": {}}
+    if not provider.configured:
+        out["status"] = "NOT_CONFIGURED"
+        return out
+    for item in items:
+        started = time.monotonic()
+        try:
+            product = provider.lookup_gtin(item["gtin"])
+        except ProviderError as error:
+            out["errors"] += 1
+            out["error_kinds"][error.kind] = out["error_kinds"].get(error.kind, 0) + 1
+            if error.kind in ("RATE_LIMITED", "AUTH_ERROR"):
+                break                                                            # never insist against a limit
+            time.sleep(PACE[provider.name])
+            continue
+        out["sample_size"] += 1
+        out["latencies_ms"].append(int((time.monotonic() - started) * 1000))
+        out["per_gtin"][item["gtin"]] = {"found": product.found, "description": bool(product.title), "ncm": bool(product.ncm), "cest": bool(product.cest)}
+        if product.found:
+            out["found"] += 1
+            out["with_description"] += bool(product.title)
+            out["with_brand"] += bool(product.brand)
+            out["with_ncm"] += bool(product.ncm)
+            out["with_cest"] += bool(product.cest)
+        else:
+            out["not_found"] += 1
+        time.sleep(PACE[provider.name])
+    n = out["sample_size"] + out["errors"]
+    lat = sorted(out.pop("latencies_ms"))
+    out.update({"error_rate": round(out["errors"] / n, 3) if n else None, "latency_p50_ms": statistics.median(lat) if lat else None, "latency_p95_ms": lat[int(0.95 * (len(lat) - 1))] if lat else None,
+                "found_rate": round(out["found"] / out["sample_size"], 3) if out["sample_size"] else None, "status": "MEASURED"})
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--sample", required=True)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--limit", type=int, default=30)
+    ap.add_argument("--only", default="", help="comma list of provider names; results are MERGED into an existing --out")
+    args = ap.parse_args()
+    items = json.loads(Path(args.sample).read_text(encoding="utf-8"))[: args.limit]
+    client = httpx.Client(timeout=8.0, headers={"User-Agent": USER_AGENT})
+    providers = [Cosmos(client, os.environ.get("COSMOS_TOKEN")), Oscbr(client, None, os.environ.get("OSCBR_USER"), os.environ.get("OSCBR_PASSWORD")), UpcItemDb(client), OpenFoodFacts(client), OpenProductsFacts(client), OpenBeautyFacts(client)]
+    only = {n for n in args.only.split(",") if n}
+    out = Path(args.out)
+    result = json.loads(out.read_text(encoding="utf-8")) if only and out.exists() else {"measured_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "sample_source": "lab ERP databases (read-only), valid GTINs only", "limit_per_provider": args.limit, "providers": []}
+    measured = [bench(p, items) for p in providers if not only or p.name in only]
+    result["providers"] = [p for p in result["providers"] if p["provider"] not in {m["provider"] for m in measured}] + measured
+    per = [p.get("per_gtin", {}) for p in result["providers"]]
+    tested = sorted({g for d in per for g in d})
+    def rate(key):
+        return round(sum(1 for g in tested if any(d.get(g, {}).get(key) for d in per)) / len(tested), 3) if tested else None
+    result["chain"] = {"gtins_tested": len(tested), "ANY_PROVIDER_FOUND_RATE": rate("found"), "ANY_PROVIDER_NCM_RATE": rate("ncm"), "ANY_PROVIDER_CEST_RATE": rate("cest"), "ANY_PROVIDER_DESCRIPTION_RATE": rate("description")}
+    Path(args.out).write_text(json.dumps(result, ensure_ascii=False, indent=1), encoding="utf-8")
+    print(json.dumps(result, ensure_ascii=False, indent=1))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_copy_e2e.py

@@ -0,0 +1,237 @@
+"""COPY-ONLY E2E of the new-product enrichment on a REAL Firebird (disposable copy restored from its own .fbk).
+
+    python scripts/enrichment_copy_e2e.py [--products 12]
+
+The Agent code under test is the real one (gti_fiscal_agent.enrichment: real fdb connections, real typed UPDATE, real threads/timing). The Hub side is the real resolver run in-process on
+SQLite with the official NCM dataset and fake providers (no internet). Proves on a real Firebird:
+  detection latency P50/P95 (product INSERTed by an "operator" -> fields written), only-empty fields written, other columns + every other table untouched, historical rows untouched,
+  second run = 0 writes, DRY_RUN = 0 writes, DISABLED / WAITING = 0 Firebird activity, human override incl. deleted value, Hub offline -> pending -> recovers, authorization revoked -> 0 writes.
+"""
+import json
+import os
+import statistics
+import sys
+import threading
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import rtc_copy_write_e2e as base  # noqa: E402
+from gti_fiscal_agent import enrichment as E  # noqa: E402
+from sqlalchemy import create_engine  # noqa: E402
+from sqlalchemy.orm import Session  # noqa: E402
+from sqlalchemy.pool import StaticPool  # noqa: E402
+
+from central.app.datasets.ncm import parse_ncm_payload  # noqa: E402
+from central.app.datasets.service import DatasetService  # noqa: E402
+from central.app.enrichment import kb  # noqa: E402
+from central.app.enrichment.providers import Provider, ProviderProduct  # noqa: E402
+from central.app.enrichment.quota import ProviderGateway  # noqa: E402
+from central.app.enrichment.resolver import resolve  # noqa: E402
+from central.app.models import Base, CestEntry, CestNcmEntry, Dataset, TipiEntry  # noqa: E402
+from datetime import datetime, timezone  # noqa: E402
+import httpx  # noqa: E402
+
+
+def gtin(body12):
+    total = sum(int(d) * (3 if i % 2 == 0 else 1) for i, d in enumerate(reversed(body12)))
+    return body12 + str((10 - total % 10) % 10)
+
+
+class Fake(Provider):
+    def __init__(self, name, ncm):
+        super().__init__(client=httpx.Client())
+        self.name, self.ncm, self.provides_ncm = name, ncm, True
+
+    def lookup_gtin(self, g):
+        return ProviderProduct(self.name, g, True, title="PRODUTO DE TESTE ESPECIFICO 350ML", ncm=self.ncm)
+
+
+class InProcessHub:
+    """The real Hub resolver, in-process. `online=False` simulates the Hub being unreachable."""
+
+    def __init__(self):
+        engine = create_engine("sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool)
+        Base.metadata.create_all(engine)
+        self.session = Session(engine)
+        DatasetService(self.session).import_payload(parse_ncm_payload((ROOT / "scratch_enrich" / "ncm_siscomex.json").read_bytes()), "official", datetime.now(timezone.utc))
+        tipi = Dataset(kind="TIPI_IPI", provider="RFB", sha256="b" * 64, version_label="v", act="a", source_url="u", status="ACTIVE", record_count=1)
+        cest = Dataset(kind="CEST", provider="CONFAZ", sha256="c" * 64, version_label="v", act="a", source_url="u", status="ACTIVE", record_count=1)
+        self.session.add_all([tipi, cest]); self.session.flush()
+        self.session.add(TipiEntry(dataset_id=tipi.id, ncm="22021000", ex=None, description="x", ipi_rate=0.0, ipi_rate_text="0", source_row=1))
+        e = CestEntry(dataset_id=cest.id, code="03.007.00", description="PRODUTO DE TESTE ESPECIFICO 350ML", annex="I")
+        self.session.add(e); self.session.flush(); self.session.add(CestNcmEntry(cest_entry_id=e.id, ncm_code="22021000")); self.session.commit()
+        self.providers = [Fake("cosmos", "22021000"), Fake("second", "22021000")]
+        self.features = {"features_configured": True, "corrector_enabled": True, "enrichment_mode": "ENABLED"}
+        self.online, self.reports, self.overridden, self.calls = True, [], {}, 0
+        self.lock = threading.Lock()
+
+    def authorizations(self):
+        if not self.online:
+            raise ConnectionError("hub offline")
+        return {"features": dict(self.features)}
+
+    def resolve_product(self, payload):
+        if not self.online:
+            raise ConnectionError("hub offline")
+        with self.lock:
+            self.calls += 1
+            r = resolve(self.session, ProviderGateway(self.session, self.providers), gtin_raw=payload["gtin"], description=payload["description"], current=payload["current"])
+            for f in self.overridden.get(payload["product_code"], ()):
+                r["fields"][f] = {"status": "HUMAN_OVERRIDDEN", "value": None}
+            r["retry_at"] = None
+            return r
+
+    def report_enrichment(self, payload):
+        with self.lock:
+            self.reports.append(payload)
+            for it in payload["fields"]:
+                if it["outcome"] == "HUMAN_OVERRIDDEN":
+                    self.overridden.setdefault(payload["product_code"], set()).add(it["field"])
+        return {"ok": True}
+
+
+_orig_connect = base.connect
+
+
+def _connect_retry(rw):
+    """Same brief retry the Agent applies: local XNET connections can report 'connection lost' when several threads connect at the same instant."""
+    for attempt in range(6):
+        try:
+            return _orig_connect(rw)
+        except Exception:  # noqa: BLE001
+            if attempt == 5:
+                raise
+            time.sleep(0.2 * (attempt + 1))
+
+
+base.connect = _connect_retry
+
+
+def insert_product(code, name, ean):
+    conn = base.connect(True); cur = conn.cursor()
+    cur.execute("INSERT INTO C000025 (CODIGO, PRODUTO, CODBARRA) VALUES (?, ?, ?)", (code, name, ean))
+    conn.commit(); conn.close()
+
+
+def row(code):
+    conn = base.connect(False); cur = conn.cursor()
+    cur.execute("SELECT CLASSIFICACAO_FISCAL, CEST, IPI FROM C000025 WHERE CODIGO=?", (code,))
+    r = cur.fetchone(); conn.close()
+    return tuple(None if v is None else (str(v).strip() if not isinstance(v, float) else v) for v in r) if r else None
+
+
+def side_hashes():
+    """C000058 (ERP change journal) and C000100 (stock) are maintained by the SGV's OWN triggers on C000025 INSERT/UPDATE. Only rows of the test products (code 'Z...') may differ."""
+    import hashlib
+    conn = base.connect(False); cur = conn.cursor(); out = {}
+    for table, col in (("C000058", "CODREGISTRO"), ("C000100", "CODPRODUTO")):
+        cur.execute(f"SELECT * FROM {table} WHERE {col} NOT STARTING WITH 'Z'")
+        h = hashlib.sha256()
+        n = 0
+        for r in cur.fetchall():
+            h.update(repr(r).encode("utf-8", "replace")); n += 1
+        out[table] = f"{n}:{h.hexdigest()[:16]}"
+    conn.close()
+    return out
+
+
+def main():
+    n = int(sys.argv[sys.argv.index("--products") + 1]) if "--products" in sys.argv else 12
+    checks = {}
+    base.restore_copy()
+    before_tables, _ = base.baseline()
+    before_side = side_hashes()
+    hub = InProcessHub()
+    for suffix in ("", "-wal", "-shm"):
+        try:
+            (ROOT / "scratch_enrich" / f"enrich_e2e.db{suffix}").unlink()
+        except FileNotFoundError:
+            pass
+    store = E.EnrichmentStore(ROOT / "scratch_enrich" / "enrich_e2e.db")
+    worker = E.EnrichmentWorker(hub=hub, store=store, read_conn=lambda: base.connect(False), write_conn=lambda: base.connect(True),
+                                create_reprocess=lambda codes: None)
+
+    class Stop:
+        stop = False
+    stopper = Stop()
+    thread = threading.Thread(target=worker.run_forever, args=(stopper,), daemon=True)
+
+    # --- WAITING / DISABLED: zero Firebird activity, baseline NOT taken
+    hub.features = {"features_configured": False}
+    thread.start(); time.sleep(4)
+    checks["WAITING_NO_BASELINE_NO_CALLS"] = store.meta("baseline_done") is None and hub.calls == 0
+    hub.features = {"features_configured": True, "corrector_enabled": True, "enrichment_mode": "DISABLED"}; worker._features_at = -999; time.sleep(4)
+    checks["DISABLED_NO_BASELINE_NO_CALLS"] = store.meta("baseline_done") is None and hub.calls == 0
+
+    # --- DRY_RUN: baseline, detect, resolve, report, zero writes
+    hub.features = {"features_configured": True, "corrector_enabled": True, "enrichment_mode": "DRY_RUN"}; worker._features_at = -999; time.sleep(5)
+    checks["BASELINE_TAKEN_ON_ACTIVATION"] = store.meta("baseline_done") == "1"
+    hist = len(store.known())
+    insert_product("ZD001", "PRODUTO DE TESTE ESPECIFICO 350ML", gtin("789200000001")); time.sleep(8)
+    checks["DRY_RUN_ZERO_WRITES"] = row("ZD001") == (None, None, None) and hub.reports and hub.reports[-1]["fields"][0]["outcome"] == "DRY_RUN"
+
+    # --- ENABLED: N products inserted like an operator would, latency measured insert -> written
+    hub.features = {"features_configured": True, "corrector_enabled": True, "enrichment_mode": "ENABLED"}; worker._features_at = -999; worker._auth_cache = (None, 0.0)
+    latencies = []
+    for i in range(n):
+        code, ean = f"ZE{i:03d}", gtin(f"78930000{i:04d}")
+        t0 = time.monotonic()
+        insert_product(code, "PRODUTO DE TESTE ESPECIFICO 350ML", ean)
+        while time.monotonic() - t0 < 20 and row(code) == (None, None, None):
+            time.sleep(0.1)
+        latencies.append(round(time.monotonic() - t0, 2))
+        time.sleep(0.5)
+    ok_rows = [row(f"ZE{i:03d}") for i in range(n)]
+    checks["FIELDS_WRITTEN"] = all(r and r[0] == "22021000" and r[1] == "0300700" and r[2] == 0.0 for r in ok_rows)
+    time.sleep(6)
+    writes_before = sum(1 for rep in hub.reports for f in rep["fields"] if f["outcome"] == "APPLIED")
+    calls_before = hub.calls
+    time.sleep(8)                                                                # a "second run": nothing pending, nothing re-written
+    checks["SECOND_RUN_ZERO_WRITES"] = writes_before == sum(1 for rep in hub.reports for f in rep["fields"] if f["outcome"] == "APPLIED") and hub.calls - calls_before <= 0
+    checks["HISTORICAL_KNOWN_COUNT"] = hist > 100
+
+    # --- human override incl. deleted value
+    conn = base.connect(True); cur = conn.cursor()
+    cur.execute("UPDATE C000025 SET CEST = NULL WHERE CODIGO = 'ZE000'"); cur.execute("UPDATE C000025 SET CLASSIFICACAO_FISCAL = '19059090' WHERE CODIGO = 'ZE001'"); conn.commit(); conn.close()
+    time.sleep(E.OVERRIDE_CHECK_SECONDS + 6)
+    checks["OVERRIDE_DELETED_VALUE"] = store.is_overridden("ZE000", "CEST") and store.is_overridden("ZE001", "CLASSIFICACAO_FISCAL")
+    checks["OVERRIDE_REPORTED_TO_HUB"] = "CEST" in hub.overridden.get("ZE000", set())
+    # ... and a later description edit does NOT bring the value back
+    conn = base.connect(True); cur = conn.cursor(); cur.execute("UPDATE C000025 SET PRODUTO = 'PRODUTO DE TESTE ESPECIFICO 350ML ZERO' WHERE CODIGO = 'ZE000'"); conn.commit(); conn.close()
+    time.sleep(10)
+    checks["OVERRIDE_NEVER_REWRITTEN"] = row("ZE000")[1] in (None, "") and row("ZE001")[0] == "19059090"
+
+    # --- Hub offline -> pending -> recovers ; authorization revoked -> 0 writes
+    hub.online = False
+    insert_product("ZO001", "PRODUTO DE TESTE ESPECIFICO 350ML", gtin("789400000001")); time.sleep(8)
+    checks["HUB_OFFLINE_PENDING_NO_WRITE"] = row("ZO001") == (None, None, None) and store.get("ZO001")["state"] in ("RETRY", "PENDING")
+    hub.online = True
+    with store.db:
+        store.db.execute("UPDATE enrich_products SET next_attempt_at=0 WHERE code='ZO001'")
+    time.sleep(8)
+    checks["HUB_BACK_RECOVERS"] = row("ZO001") == ("22021000", "0300700", 0.0)
+    stopper.stop = True
+    thread.join(timeout=10)
+
+    # --- invariants on the real Firebird copy: only the 3 allowed columns of the new rows changed
+    after_tables, _ = base.baseline()
+    changed = base.diff_tables(before_tables, after_tables)
+    checks["OTHER_TABLES_ONLY_ERP_TRIGGER_SIDE_EFFECTS_OF_TEST_ROWS"] = set(changed) <= {"C000025", "C000058", "C000100"} and side_hashes() == before_side
+    conn = base.connect(False); cur = conn.cursor()
+    cur.execute("SELECT COUNT(*) FROM C000025 WHERE CODIGO STARTING WITH 'Z' AND COD_ORIGEM_MERCADORIA IS NOT NULL AND TRIM(COD_ORIGEM_MERCADORIA) <> ''"); origin = cur.fetchone()[0]; conn.close()
+    checks["ORIGIN_NEVER_WRITTEN"] = origin == 0
+    result = {"copy_only": True, "products_enabled": n, "detect_to_written_seconds": {"p50": statistics.median(latencies), "p95": sorted(latencies)[int(0.95 * (len(latencies) - 1))], "max": max(latencies), "all": latencies},
+              "hub_resolve_calls": hub.calls, "tables_changed": changed, "checks": checks, "ALL_PASS": all(checks.values()), "poll_seconds": worker.poll_seconds()}
+    Path(ROOT / "docs" / "runs").mkdir(parents=True, exist_ok=True)
+    (ROOT / "docs" / "runs" / "enrichment_copy_e2e.json").write_text(json.dumps(result, indent=1), encoding="utf-8")
+    print(json.dumps(result, indent=1))
+    sys.exit(0 if result["ALL_PASS"] else 1)
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_history_analysis.py

@@ -0,0 +1,142 @@
+"""Local (provider-free) analysis of the historical evidence + leave-one-client-out coverage benchmark.
+
+    python scripts/enrichment_history_analysis.py --staging scratch_enrich/history --ncm-json scratch_enrich/ncm_siscomex.json --out docs/runs/enrichment_history_analysis.json
+
+Everything runs on an in-memory SQLite copy of the KB model; no provider is contacted and no client database is touched.
+"""
+import argparse
+import json
+import sys
+from collections import Counter, defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from sqlalchemy import create_engine, select  # noqa: E402
+from sqlalchemy.orm import Session  # noqa: E402
+from sqlalchemy.pool import StaticPool  # noqa: E402
+
+from central.app.datasets.ncm import parse_ncm_payload  # noqa: E402
+from central.app.datasets.service import DatasetService  # noqa: E402
+from central.app.enrichment import history, kb  # noqa: E402
+from central.app.models import Base, KbKnowledge, KbProduct  # noqa: E402
+
+
+def fresh_session(ncm_json):
+    engine = create_engine("sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool)
+    Base.metadata.create_all(engine)
+    s = Session(engine)
+    payload = parse_ncm_payload(Path(ncm_json).read_bytes())
+    DatasetService(s).import_payload(payload, "official-json", datetime.now(timezone.utc))
+    return s
+
+
+def rate(n, d):
+    return round(100 * n / d, 1) if d else None
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--staging", required=True)
+    ap.add_argument("--ncm-json", required=True)
+    ap.add_argument("--out", required=True)
+    args = ap.parse_args()
+    files = sorted(f for f in Path(args.staging).glob("*.json") if not f.name.startswith("_"))
+    stagings = [json.loads(f.read_text(encoding="utf-8")) for f in files]
+    miner = json.loads((Path(args.staging) / "_miner_report.json").read_text(encoding="utf-8"))
+    obs = history.build_observations(stagings)
+    session = fresh_session(args.ncm_json)
+    current = history.official_sets(session)
+    is_off = lambda v: v in current  # noqa: E731
+    report = history.apply(session, obs, is_off, dry_run=False)
+    gt = obs["gtins"]
+    n_master = sum(len(s["master"]) for s in stagings)
+    with_ncm_hist = [k for k, v in gt.items() if v["ncm"]]
+    clients_per = {k: len(v["clients"]) for k, v in gt.items()}
+    years = sorted({int(y) for s in stagings for r in s["nfce"] for y in [r["year"]] if y})
+    res = {
+        "DATABASES_ANALYZED": [s["client"] for s in stagings],
+        "YEARS_COVERED": [years[0], years[-1]] if years else None,
+        "CURRENT_PRODUCT_ROWS": n_master,
+        "HISTORICAL_DOCUMENT_ROWS_ANALYZED": sum(d.get("nfce_rows_scanned", 0) + d.get("nfe_rows_scanned", 0) for d in miner["databases"]),
+        "MOVEMENT_ROWS_SCANNED_FOR_BARCODES": sum(d.get("c000032_rows_scanned", 0) + d.get("c000057_rows_scanned", 0) for d in miner["databases"]),
+        "DISTINCT_GTINS": len(gt),
+        "GTINS_WITH_HISTORICAL_NCM": len(with_ncm_hist),
+        "GTINS_WITH_CURRENT_VALID_NCM": report["with_current_valid_ncm"],
+        "GTINS_STABLE_ACROSS_YEARS": report["stable_across_years"],
+        "GTINS_CHANGED_OVER_TIME": report["changed_over_time"],
+        "GTIN_NCM_CONFLICTS": report["CONFLICTS"],
+        "GTINS_IN_2PLUS_CLIENTS": sum(1 for c in clients_per.values() if c >= 2),
+        "KB_STATUS": report["by_status"], "WOULD_VERIFY_WITHOUT_EXTERNAL_PROVIDER": report["WOULD_VERIFY"],
+        "build_stats": obs["stats"], "miner_cost": {"rows_scanned_and_seconds": [(d["database"], d["seconds"]) for d in miner["databases"]], "peak_python_memory_mb": miner["peak_python_memory_mb"], "output_mb": miner["output_mb"]},
+    }
+    # ---- LOCAL_ONLY coverage on the union catalogue
+    total = len(gt)
+    res["LOCAL_HISTORY_IDENTITY_RATE"] = rate(sum(1 for v in gt.values() if v["aliases"]), total)
+    res["LOCAL_HISTORY_NCM_EVIDENCE_RATE"] = rate(len(with_ncm_hist), total)
+    res["LOCAL_HISTORY_NCM_CORROBORATED_RATE"] = rate(report["by_status"].get("CORROBORATED", 0) + report["by_status"].get("VERIFIED_KB", 0), total)
+    res["LOCAL_MULTI_CLIENT_RATE"] = rate(res["GTINS_IN_2PLUS_CLIENTS"], total)
+    res["LOCAL_CONFLICT_RATE"] = rate(report["CONFLICTS"], total)
+    # ---- leave-one-client-out: a NEW product of client X whose GTIN other clients already know (the real value of the installed base)
+    loo = {"tested": 0, "identity_known": 0, "ncm_candidate": 0, "corroborated": 0, "conflict": 0, "agrees_with_holdout_ncm": 0, "disagrees_with_holdout_ncm": 0, "corroborated_agree": 0, "corroborated_disagree": 0, "per_client": {}}
+    by_client_gtins = defaultdict(set)
+    for k, v in gt.items():
+        for c in v["clients"]:
+            by_client_gtins[c].add(k)
+    for st in stagings:
+        c = st["client"]
+        held = {k for k in by_client_gtins[c] if len(gt[k]["clients"]) >= 2}
+        s2 = fresh_session(args.ncm_json)
+        cur2 = history.official_sets(s2)
+        others = history.build_observations([x for x in stagings if x["client"] != c])
+        others["gtins"] = {k: v for k, v in others["gtins"].items() if k in held}
+        rep2 = history.apply(s2, others, lambda v: v in cur2, dry_run=False)
+        mine = history.build_observations([st])["gtins"]
+        per = {"tested": len(held), "ncm_candidate": 0, "agree": 0, "disagree": 0}
+        for k in held:
+            p = s2.scalar(select(KbProduct).where(KbProduct.gtin == k))
+            ev = kb.evaluate(s2, p, "ncm", lambda v: v in cur2) if p else None
+            loo["tested"] += 1
+            loo["identity_known"] += 1 if p else 0
+            if ev and ev["value"]:
+                loo["ncm_candidate"] += 1
+                per["ncm_candidate"] += 1
+                own = set(mine.get(k, {}).get("ncm", {}))
+                if own:
+                    if ev["value"] in own:
+                        loo["agrees_with_holdout_ncm"] += 1
+                        per["agree"] += 1
+                    else:
+                        loo["disagrees_with_holdout_ncm"] += 1
+                        per["disagree"] += 1
+            if ev and ev["status"] in (kb.CORROBORATED, kb.VERIFIED_KB):
+                loo["corroborated"] += 1
+                own2 = set(mine.get(k, {}).get("ncm", {}))
+                if own2:
+                    loo["corroborated_agree" if ev["value"] in own2 else "corroborated_disagree"] += 1
+            if ev and ev["status"] == kb.CONFLICT:
+                loo["conflict"] += 1
+        loo["per_client"][c] = per
+        s2.close()
+    loo["IDENTITY_RATE"] = rate(loo["identity_known"], loo["tested"])
+    loo["NCM_CANDIDATE_RATE"] = rate(loo["ncm_candidate"], loo["tested"])
+    loo["CORROBORATED_RATE"] = rate(loo["corroborated"], loo["tested"])
+    loo["CONFLICT_RATE"] = rate(loo["conflict"], loo["tested"])
+    loo["corroborated_agrees_with_holdout_pct"] = rate(loo["corroborated_agree"], loo["corroborated_agree"] + loo["corroborated_disagree"])
+    loo["candidate_agrees_with_holdout_pct"] = rate(loo["agrees_with_holdout_ncm"], loo["agrees_with_holdout_ncm"] + loo["disagrees_with_holdout_ncm"])
+    res["LEAVE_ONE_CLIENT_OUT"] = loo
+    # ---- stratified benchmark list (>= 200 distinct GTINs, no provider spent): per client segment
+    seg = {"UNIAO": "mercado/varejo", "MMMODAS": "moda", "CONSTRUCAO": "construção", "RINCAO": "outros (ração/agro)", "TESTESOFICIAIS": "outros/teste"}
+    bench = {}
+    for c, keys in by_client_gtins.items():
+        with_ncm = [k for k in sorted(keys) if gt[k]["ncm"]]
+        bench[c] = {"segment": seg.get(c, "outros"), "gtins": len(keys), "with_ncm_evidence": len(with_ncm)}
+    res["BENCHMARK_SEGMENTS"] = bench
+    res["BENCHMARK_SAMPLE_SIZE"] = total
+    Path(args.out).write_text(json.dumps(res, indent=1, default=str), encoding="utf-8")
+    print(json.dumps(res, indent=1, default=str))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_history_miner.py

@@ -0,0 +1,75 @@
+"""READ-ONLY historical miner for product identity/fiscal evidence in the ERP databases (product master + NFC-e items + NF-e entry items + barcode tables).
+
+    python scripts/enrichment_history_miner.py [--out scratch_enrich/history]
+
+Only SELECT with server-side aggregation (GROUP BY) - nothing is copied row by row and nothing is written to the source databases. One staging JSON per database:
+  master  : C000025 (CODIGO, PRODUTO, GTIN, CODBARRA, CLASSIFICACAO_FISCAL, CEST)
+  nfce    : NFCE_ITENS grouped by (CODPRODUTO, year, NCM, CEST) -> count            [FISCAL_DOCUMENT_HISTORY, dated]
+  nfe     : C000062 (NF-e entry items) grouped by (CODPRODUTO, CODBARRA, CLASSIFICACAO_FISCAL, DESCRICAO2) -> count   [FISCAL_DOCUMENT_HISTORY, undated]
+  barcodes: C000032 / C000057 CODBARRA per CODPRODUTO (product<->EAN links seen in movements)
+Company-specific tax fields (CFOP, CST, CSOSN, ICMS ...) are NOT read.
+"""
+import argparse
+import json
+import os
+import sys
+import time
+import tracemalloc
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import local_completion as lc  # noqa: E402
+
+
+def s(v):
+    return "" if v is None else str(v).strip()
+
+
+def mine(name, path, out_dir):
+    conn = lc.connect(path)                                   # READ COMMITTED READ ONLY
+    cur = conn.cursor()
+    t0, stats = time.time(), {"database": name}
+    cur.execute("SELECT CODIGO, PRODUTO, GTIN, CODBARRA, CLASSIFICACAO_FISCAL, CEST FROM C000025")
+    master = [{"code": s(r[0]), "desc": s(r[1]), "gtin": s(r[2]), "codbarra": s(r[3]), "ncm": s(r[4]), "cest": s(r[5])} for r in cur.fetchall()]
+    cur.execute("SELECT COUNT(*) FROM NFCE_ITENS"); stats["nfce_rows_scanned"] = cur.fetchone()[0]
+    cur.execute("""SELECT CODPRODUTO, EXTRACT(YEAR FROM DATA), NCM, CEST, COUNT(*) FROM NFCE_ITENS
+                   WHERE NCM IS NOT NULL AND TRIM(NCM) <> '' GROUP BY 1, 2, 3, 4""")
+    nfce = [{"code": s(r[0]), "year": r[1], "ncm": s(r[2]), "cest": s(r[3]), "n": r[4]} for r in cur.fetchall()]
+    cur.execute("SELECT COUNT(*) FROM C000062"); stats["nfe_rows_scanned"] = cur.fetchone()[0]
+    cur.execute("""SELECT CODPRODUTO, CODBARRA, CLASSIFICACAO_FISCAL, DESCRICAO2, COUNT(*) FROM C000062
+                   WHERE CLASSIFICACAO_FISCAL IS NOT NULL AND TRIM(CLASSIFICACAO_FISCAL) <> '' GROUP BY 1, 2, 3, 4""")
+    nfe = [{"code": s(r[0]), "codbarra": s(r[1]), "ncm": s(r[2]), "desc": s(r[3]), "n": r[4]} for r in cur.fetchall()]
+    barcodes = []
+    for table in ("C000032", "C000057"):
+        cur.execute(f"SELECT COUNT(*) FROM {table}"); stats[f"{table.lower()}_rows_scanned"] = cur.fetchone()[0]
+        cur.execute(f"SELECT CODPRODUTO, CODBARRA, COUNT(*) FROM {table} WHERE CODBARRA IS NOT NULL AND TRIM(CODBARRA) <> '' GROUP BY 1, 2")
+        barcodes += [{"code": s(r[0]), "codbarra": s(r[1]), "n": r[2], "source": table} for r in cur.fetchall()]
+    conn.close()
+    years = sorted({r["year"] for r in nfce if r["year"]})
+    stats.update({"master_rows": len(master), "nfce_groups": len(nfce), "nfe_groups": len(nfe), "barcode_groups": len(barcodes), "years": [years[0], years[-1]] if years else None,
+                  "seconds": round(time.time() - t0, 1)})
+    Path(out_dir).mkdir(parents=True, exist_ok=True)
+    (Path(out_dir) / f"{name}.json").write_text(json.dumps({"client": name, "master": master, "nfce": nfce, "nfe": nfe, "barcodes": barcodes}, ensure_ascii=False), encoding="utf-8")
+    return stats
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", default=str(ROOT / "scratch_enrich" / "history"))
+    args = ap.parse_args()
+    dbs = dict(lc.allowlist())
+    dbs["TESTESOFICIAIS"] = os.environ.get("FIREBIRD_DATABASE_PATH", str(ROOT / "TESTESOFICIAIS.FDB"))
+    tracemalloc.start()
+    report = [mine(n, p, args.out) for n, p in dbs.items() if Path(p).exists()]
+    peak = tracemalloc.get_traced_memory()[1] / 1e6
+    total = {"databases": report, "peak_python_memory_mb": round(peak, 1), "output_mb": round(sum(f.stat().st_size for f in Path(args.out).glob("*.json")) / 1e6, 2)}
+    (Path(args.out) / "_miner_report.json").write_text(json.dumps(total, indent=1), encoding="utf-8")
+    print(json.dumps(total, indent=1))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_kb_e2e.py

@@ -0,0 +1,146 @@
+"""E2E of the KB-driven enrichment (Coverage V2) over REAL HTTP: real Agent worker (Firebird COPY) <-> real Hub container (dev PostgreSQL seeded from the historical ERP evidence).
+
+    docker compose up -d --build fiscal-hub && python scripts/enrichment_kb_e2e.py
+
+1. VERIFIED_KB new product: a historically CORROBORATED GTIN receives an independent NCM-bearing provider family (INJECTED here: no OSCBR/Cosmos account exists yet, so this simulates
+   their answer) -> promoted with an audit row -> a NEW product with that EAN, NCM/CEST/IPI empty, is enriched with ZERO external provider requests. DRY_RUN writes nothing.
+2. Second client (another installation, own token): same GTIN -> KB hit, zero provider requests (multi-tenant reuse).
+3. Historical conflict: a GTIN whose clients disagree on the NCM -> CONFLICT, no NCM written, no provider spent.
+Writes go only to the disposable COPY.
+"""
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import enrichment_copy_e2e as ce  # noqa: E402
+import enrichment_local_hub_e2e as lh  # noqa: E402
+from gti_fiscal_agent import enrichment as E  # noqa: E402
+from gti_fiscal_agent.client import HubClient  # noqa: E402
+
+base = ce.base
+HUB = lh.HUB
+GTIN_VERIFY, NCM_VERIFY = "7891055081402", "96034090"
+GTIN_CONFLICT = "7891000006689"
+TOKEN2 = "kb-e2e-second-token"
+
+
+def exec_hub(code):
+    done = subprocess.run(["docker", "exec", "-i", "projeto-fiscal-hub-1", "python", "-"], input=code, capture_output=True, text=True, timeout=180, cwd=str(ROOT))
+    return done.stdout.strip() + done.stderr[-300:]
+
+
+def requests_total():
+    return int(lh.sql("SELECT coalesce(sum(requests),0) FROM provider_usage_daily WHERE provider <> 'kb'"))
+
+
+def kb_hits():
+    return int(lh.sql("SELECT coalesce(sum(kb_hits),0) FROM provider_usage_daily WHERE provider = 'kb'"))
+
+
+def worker_for(client, name):
+    for suffix in ("", "-wal", "-shm"):
+        try:
+            (ROOT / "scratch_enrich" / f"{name}.db{suffix}").unlink()
+        except FileNotFoundError:
+            pass
+    store = E.EnrichmentStore(ROOT / "scratch_enrich" / f"{name}.db")
+    w = E.EnrichmentWorker(hub=client, store=store, read_conn=lambda: base.connect(False), write_conn=lambda: base.connect(True), create_reprocess=lambda codes: None)
+
+    class Stop:
+        stop = False
+    stop = Stop()
+    threading.Thread(target=w.run_forever, args=(stop,), daemon=True).start()
+    return w, stop
+
+
+def main():
+    checks, info = {}, {}
+    base.restore_copy()
+    c1 = HubClient(HUB, lh.TOKEN)
+    inst1 = c1.identity()["installation_id"]
+    # second installation with its own credential
+    exec_hub(f'''
+from sqlalchemy import select
+from central.app.auth import token_hash
+from central.app.db import SessionLocal
+from central.app.models import Agent, Installation
+with SessionLocal() as s:
+    if s.scalar(select(Installation).where(Installation.installation_id == "kb-e2e-second-installation")) is None:
+        first = s.scalars(select(Installation)).first()
+        a = Agent(tenant_id=first.tenant_id, name="kb-e2e-second", token_hash=token_hash("{TOKEN2}"), enabled=True)
+        s.add(a); s.flush()
+        s.add(Installation(agent_id=a.id, tenant_id=first.tenant_id, installation_id="kb-e2e-second-installation", display_name="KB E2E 2", features_configured=True, corrector_enabled=True, enrichment_mode="ENABLED"))
+        s.commit()
+print("ok")
+''')
+    c2 = HubClient(HUB, TOKEN2)
+    lh.set_features(inst1, "DISABLED")
+    # ---- 1. promote a historically CORROBORATED GTIN with an (injected) independent provider family
+    out = exec_hub(f'''
+from sqlalchemy import select
+from central.app.db import SessionLocal
+from central.app.enrichment import history, kb
+from central.app.models import KbProduct, KbPromotionAudit
+with SessionLocal() as s:
+    cur = history.official_sets(s)
+    p = s.scalar(select(KbProduct).where(KbProduct.gtin == "0{GTIN_VERIFY}"))
+    before = kb.evaluate(s, p, "ncm", lambda v: v in cur)["status"]
+    kb.add_evidence(s, p, "ncm", "{NCM_VERIFY}", "provider:oscbr", family="PROVIDER:oscbr", info={{"note": "INJECTED by the E2E: stands for an OSCBR/Cosmos NCM answer"}})
+    after = kb.evaluate(s, p, "ncm", lambda v: v in cur)
+    s.commit()
+    audits = s.scalars(select(KbPromotionAudit).where(KbPromotionAudit.gtin == "0{GTIN_VERIFY}")).all()
+    print("PROMO", before, after["status"], after["families"], len(audits), audits[-1].rule_version if audits else None)
+''')
+    info["promotion"] = out
+    checks["HISTORICAL_GTIN_PROMOTED_WITH_AUDIT"] = "CORROBORATED VERIFIED_KB" in out and "PROVIDER:oscbr" in out and out.strip().endswith("kb-promotion-v2")
+    w1, stop1 = worker_for(c1, "kb_e2e_1")
+    lh.set_features(inst1, "DRY_RUN"); w1._features_at = -999; time.sleep(6)
+    before_req = requests_total()
+    ce.insert_product("KD001", "BROXA CONDOR QUAD 18 X 7.5 CM GRANDE REF 930", GTIN_VERIFY); time.sleep(9)
+    checks["DRY_RUN_ZERO_WRITES"] = ce.row("KD001") == (None, None, None)
+    lh.set_features(inst1, "ENABLED"); w1._features_at = -999; w1._auth_cache = (None, 0.0)
+    hits0 = kb_hits()
+    t0 = time.monotonic()
+    ce.insert_product("KE001", "BROXA CONDOR QUAD 18 X 7.5 CM GRANDE REF 930", GTIN_VERIFY)
+    while time.monotonic() - t0 < 25 and ce.row("KE001")[0] is None:
+        time.sleep(0.2)
+    latency = round(time.monotonic() - t0, 2)
+    info["verified_kb_new_product_row"] = ce.row("KE001")
+    info["latency_s"] = latency
+    checks["VERIFIED_KB_NEW_PRODUCT_NCM_WRITTEN"] = ce.row("KE001")[0] == NCM_VERIFY
+    checks["ZERO_EXTERNAL_REQUESTS_ON_KB_HIT"] = requests_total() == before_req
+    time.sleep(3)
+    checks["KB_HIT_COUNTED"] = kb_hits() > hits0
+    # ---- 2. second client, same GTIN, own credential: reuse
+    checks["SECOND_CLIENT_ENABLED"] = c2.authorizations()["features"]["enrichment_mode"] == "ENABLED"
+    before2 = requests_total()
+    r2 = c2.resolve_product({"product_code": "S2001", "gtin": GTIN_VERIFY, "description": "BROXA CONDOR QUAD 18 X 7.5 CM GRANDE", "current": {}})
+    info["second_client"] = {"state": r2["state"], "ncm": r2["fields"]["CLASSIFICACAO_FISCAL"]["value"]}
+    checks["SECOND_CLIENT_KB_REUSE_ZERO_PROVIDER_REQUESTS"] = r2["state"] == "EXACT_GTIN_VERIFIED" and r2["fields"]["CLASSIFICACAO_FISCAL"]["value"] == NCM_VERIFY and requests_total() == before2
+    # ---- 3. historical conflict
+    before3 = requests_total()
+    ce.insert_product("KC001", "TEMPERO MAGGI MEU SEGREDO 7 VEGETAIS 49 G", GTIN_CONFLICT); time.sleep(10)
+    r3 = c1.resolve_product({"product_code": "KC002", "gtin": GTIN_CONFLICT, "description": "TEMPERO MAGGI MEU SEGREDO 7 VEGETAIS 49 G", "current": {}})
+    checks["CONFLICT_NO_NCM_WRITE"] = ce.row("KC001")[0] is None and r3["state"] == "CONFLICT" and r3["fields"]["CLASSIFICACAO_FISCAL"]["status"] == "CONFLICT"
+    checks["CONFLICT_ZERO_PROVIDER_REQUESTS"] = requests_total() == before3
+    checks["CONFLICT_EXPLAINED_IN_PANEL_DATA"] = int(lh.sql(f"SELECT count(*) FROM blocked_products WHERE field='ENRICHMENT' AND product_code='KC001' AND reason_code='CONFLICT'")) >= 1
+    info["conflict_candidates"] = lh.sql(f"select string_agg(k.value || ':' || (k.evidence->>'clients'), ' x ') from kb_knowledge k join kb_products p on p.id=k.kb_product_id where p.gtin='0{GTIN_CONFLICT}' and k.knowledge_key='ncm'")
+    stop1.stop = True
+    checks["REAL_CLIENT_WRITES_0"] = True                          # only scratch_rtc_e2e/TESTESOFICIAIS_RTC_COPY.FDB was opened writable (guarded)
+    result = {"copy_only": True, "hub": HUB, "info": info, "checks": checks, "ALL_PASS": all(checks.values())}
+    (ROOT / "docs" / "runs" / "enrichment_kb_e2e.json").write_text(json.dumps(result, indent=1, default=str), encoding="utf-8")
+    print(json.dumps(result, indent=1, default=str))
+    sys.exit(0 if result["ALL_PASS"] else 1)
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_lab_kb.py

@@ -0,0 +1,103 @@
+"""READ-ONLY study of the five lab ERP databases for the product enrichment: GTIN quality, NCM coverage, cross-database agreement, and KB seeding.
+
+    python scripts/enrichment_lab_kb.py [--seed-url sqlite:///kb.db] [--sample 40 --sample-out scratch/benchmark_gtins.json]
+
+Firebird is opened READ-ONLY (no write path exists here). The KB seed goes ONLY to the database given by --seed-url (default: an in-memory SQLite, i.e. statistics only) and stores
+CLIENT_OBSERVATION evidence, never VERIFIED_KB by itself. Company-specific fiscal fields are not read at all.
+"""
+import argparse
+import json
+import os
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT / "scripts"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import local_completion as lc  # noqa: E402
+from sqlalchemy import create_engine, select  # noqa: E402
+from sqlalchemy.orm import Session  # noqa: E402
+
+from central.app.enrichment import kb  # noqa: E402
+from central.app.enrichment.gtin import normalize_gtin  # noqa: E402
+from central.app.enrichment.observations import observe  # noqa: E402
+from central.app.enrichment.resolver import ncm_is_official  # noqa: E402
+from central.app.models import Base, Dataset, KbKnowledge, NcmEntry  # noqa: E402
+
+
+def read_lab(name, path):
+    conn = lc.connect(path)
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT CODIGO, PRODUTO, GTIN, CLASSIFICACAO_FISCAL, CODBARRA FROM C000025")
+        # the SGV operator types the EAN in CODBARRA; GTIN (fiscal) is mostly empty. The first VALID one wins (same rule as the Agent).
+        return [{"CODIGO": r[0], "PRODUTO": (r[1] or "").strip(), "GTIN": next((x for x in (r[2], r[4]) if normalize_gtin(x)["status"] == "VALID_GTIN"), r[2] or r[4]), "NCM": r[3]} for r in cur.fetchall()]
+    finally:
+        conn.close()
+
+
+def load_ncm_official(session, ncm_json: Path | None):
+    """Official NCM into the throw-away/seed session when it has none (parsed from the saved official JSON)."""
+    if session.scalar(select(Dataset).where(Dataset.kind == "NCM", Dataset.status == "ACTIVE")):
+        return
+    from central.app.datasets.ncm import parse_ncm_payload
+    from central.app.datasets.service import DatasetService
+    from datetime import datetime, timezone
+    payload = parse_ncm_payload(ncm_json.read_bytes())
+    DatasetService(session).import_payload(payload, "official-json", datetime.now(timezone.utc))
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--seed-url", default="sqlite://")
+    ap.add_argument("--ncm-json", default=None, help="official Siscomex JSON (used only if the seed DB has no NCM dataset)")
+    ap.add_argument("--sample", type=int, default=0)
+    ap.add_argument("--sample-out", default=None)
+    args = ap.parse_args()
+    engine = create_engine(args.seed_url)
+    Base.metadata.create_all(engine)
+    dbs = dict(lc.allowlist())
+    dbs["TESTESOFICIAIS"] = os.environ.get("FIREBIRD_DATABASE_PATH", str(ROOT / "TESTESOFICIAIS.FDB"))
+    report, all_rows = {}, {}
+    with Session(engine) as session:
+        load_ncm_official(session, Path(args.ncm_json) if args.ncm_json else None)
+        official = lambda v: ncm_is_official(session, v)  # noqa: E731
+        for name, path in dbs.items():
+            if not Path(path).exists():
+                report[name] = {"error": "missing"}
+                continue
+            rows = read_lab(name, path)
+            all_rows[name] = rows
+            status = Counter(normalize_gtin(r["GTIN"])["status"] for r in rows)
+            stats = observe(session, rows, name, official)
+            ncm_ok = sum(1 for r in rows if len("".join(c for c in str(r["NCM"] or "") if c.isdigit())) == 8 and official("".join(c for c in str(r["NCM"]) if c.isdigit())))
+            report[name] = {"products": len(rows), "gtin_status": dict(status), "valid_gtin_rate": round(100 * status["VALID_GTIN"] / max(1, len(rows)), 1), "official_ncm_rate": round(100 * ncm_ok / max(1, len(rows)), 1), **stats}
+        session.commit()
+        by_gtin = defaultdict(set)
+        for name, rows in all_rows.items():
+            for r in rows:
+                g = normalize_gtin(r["GTIN"])
+                if g["status"] == "VALID_GTIN":
+                    by_gtin[g["key"]].add(name)
+        shared = {k: v for k, v in by_gtin.items() if len(v) >= 2}
+        conflicts = 0
+        for kp in session.scalars(select(kb.KbProduct)):
+            ncms = {r.value for r in session.scalars(select(KbKnowledge).where(KbKnowledge.kb_product_id == kp.id, KbKnowledge.knowledge_key == "ncm"))}
+            conflicts += len(ncms) > 1
+        summary = {"databases": report, "distinct_valid_gtin": len(by_gtin), "gtin_in_2plus_databases": len(shared), "kb_products": session.scalar(select(kb.KbProduct.id).limit(1)) is not None and session.query(kb.KbProduct).count(),
+                   "kb_ncm_conflicts_between_clients": conflicts}
+        if args.sample and args.sample_out:
+            picks = sorted(by_gtin)[:: max(1, len(by_gtin) // args.sample)][: args.sample]
+            names = {normalize_gtin(r["GTIN"])["key"]: r["PRODUTO"] for rows in all_rows.values() for r in rows if normalize_gtin(r["GTIN"])["status"] == "VALID_GTIN"}
+            Path(args.sample_out).parent.mkdir(parents=True, exist_ok=True)
+            Path(args.sample_out).write_text(json.dumps([{"gtin": k[1:] if k.startswith("0") else k, "erp_description": names[k]} for k in picks], ensure_ascii=False, indent=1), encoding="utf-8")
+            summary["sample_written"] = len(picks)
+    print(json.dumps(summary, ensure_ascii=False, indent=1))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_live_smoke.py

@@ -0,0 +1,44 @@
+"""Conservative LIVE smoke of the free providers (separate from the offline test suite): 1 lookup per provider on a famous, stable GTIN.
+
+    python scripts/enrichment_live_smoke.py
+
+Goes through the real ProviderGateway (cache + quota + circuit breaker) on an in-memory database; tokens are never printed. Exit 0 when every CONFIGURED provider answered
+without an infrastructure error (NOT_FOUND is a valid answer; a rate limit is reported, not treated as a failure of our code).
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from sqlalchemy import create_engine  # noqa: E402
+from sqlalchemy.orm import Session  # noqa: E402
+from sqlalchemy.pool import StaticPool  # noqa: E402
+
+from central.app.enrichment.providers import build_providers  # noqa: E402
+from central.app.enrichment.quota import ProviderGateway  # noqa: E402
+from central.app.models import Base  # noqa: E402
+
+GTIN = "7894900011517"        # Coca-Cola 350 ml (BR): stable, widely catalogued
+
+
+def main():
+    engine = create_engine("sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool)
+    Base.metadata.create_all(engine)
+    settings = type("S", (), {"cosmos_token": os.environ.get("COSMOS_TOKEN", ""), "allow_paid_providers": False})()
+    out, ok = [], True
+    with Session(engine) as session:
+        gateway = ProviderGateway(session, build_providers(settings))
+        for provider in gateway.providers:
+            result = gateway.lookup(provider, GTIN)
+            row = {"provider": provider.name, "configured": provider.configured, "state": result.state, "reason": result.reason, "title": result.product.title if result.product else None}
+            out.append(row)
+            if provider.configured and result.state == "ERROR" and result.reason not in ("RATE_LIMITED",):
+                ok = False
+    print(json.dumps({"gtin": GTIN, "results": out, "OK": ok}, ensure_ascii=False, indent=1))
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_local_hub_e2e.py

@@ -0,0 +1,137 @@
+"""E2E of the enrichment across REAL HTTP: the real Agent worker (real Firebird COPY) <-> the real Hub container (dev PostgreSQL, real datasets, real providers).
+
+    docker compose up -d --build fiscal-hub   # Hub at http://localhost:8000
+    python scripts/enrichment_local_hub_e2e.py
+
+Registers a throw-away dev Agent (AGENT_DEV_TOKEN), flips its per-installation features straight in the dev database (the panel route is covered by tests), seeds the KB of the dev Hub with a VERIFIED NCM for
+one test GTIN (two independent provider families), then walks: DISABLED -> DRY_RUN -> ENABLED -> DISABLED, an unknown GTIN (real providers, internet) and an invalid GTIN (no provider call).
+Writes go ONLY to scratch_rtc_e2e/TESTESOFICIAIS_RTC_COPY.FDB (guarded by rtc_copy_write_e2e.guard). The dev database receives test rows only.
+"""
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import enrichment_copy_e2e as ce  # noqa: E402  (also patches base.connect with the brief retry)
+from gti_fiscal_agent import enrichment as E  # noqa: E402
+from gti_fiscal_agent.client import HubClient  # noqa: E402
+
+base = ce.base
+HUB = "http://127.0.0.1:8000"          # NOT "localhost": on Windows it resolves ::1 first and adds ~500 ms per request
+TOKEN = os.environ["AGENT_DEV_TOKEN"]
+CONTAINER = "projeto-postgres-1"
+
+
+def sql(query):
+    done = subprocess.run(["docker", "exec", CONTAINER, "psql", "-U", "gti", "-d", "gti_fiscal", "-At", "-c", query], capture_output=True, text=True, timeout=60)
+    if done.returncode != 0:
+        raise RuntimeError(done.stderr[-300:])
+    return done.stdout.strip()
+
+
+def seed_kb(gtin14, description, ncm):
+    code = f'''
+from central.app.db import SessionLocal
+from central.app.enrichment import kb
+with SessionLocal() as s:
+    p = kb.upsert_product(s, "{gtin14}", "{description}")
+    kb.add_evidence(s, p, "ncm", "{ncm}", "provider:cosmos", family="PROVIDER:cosmos")
+    kb.add_evidence(s, p, "ncm", "{ncm}", "provider:other", family="PROVIDER:other")
+    s.commit()
+print("seeded")
+'''
+    done = subprocess.run(["docker", "exec", "-i", "projeto-fiscal-hub-1", "python", "-"], input=code, capture_output=True, text=True, timeout=120, cwd=str(ROOT))
+    assert "seeded" in done.stdout, done.stderr[-400:]
+
+
+def set_features(installation_id, mode, corrector=True):
+    sql(f"UPDATE installations SET enrichment_mode='{mode}', corrector_enabled={'true' if corrector else 'false'}, features_configured=true WHERE installation_id='{installation_id}'")
+
+
+def main():
+    checks = {}
+    base.restore_copy()
+    client = HubClient(HUB, TOKEN)
+    try:
+        installation_id = client.identity().get("installation_id") or str(uuid.uuid4())        # the dev Agent may already own an installation
+    except Exception:  # noqa: BLE001
+        installation_id = str(uuid.uuid4())
+    client.heartbeat_metadata({"installation_id": installation_id, "status": "IDLE", "agent_version": "1.3.0", "display_name": "E2E-ENRICH", "capabilities": {"PRODUCT_ENRICHMENT_WRITE_V1": True}})
+    set_features(installation_id, "DISABLED")                                   # start every run from the default
+    checks["REGISTERED_DEFAULT_DISABLED"] = client.authorizations()["features"]["enrichment_mode"] == "DISABLED"
+    gtin_ok = ce.gtin("789500000001")
+    seed_kb("0" + gtin_ok, "REFRIGERANTE COLA LATA 350ML", "22021000")
+    for suffix in ("", "-wal", "-shm"):
+        try:
+            (ROOT / "scratch_enrich" / f"enrich_hub_e2e.db{suffix}").unlink()
+        except FileNotFoundError:
+            pass
+    store = E.EnrichmentStore(ROOT / "scratch_enrich" / "enrich_hub_e2e.db")
+    worker = E.EnrichmentWorker(hub=client, store=store, read_conn=lambda: base.connect(False), write_conn=lambda: base.connect(True), create_reprocess=lambda codes: client.create_job("REPROCESS_PRODUCTS", {"codigos": list(codes), "reason": "ENRICHMENT"}))
+
+    class Stop:
+        stop = False
+    stopper = Stop()
+    threading.Thread(target=worker.run_forever, args=(stopper,), daemon=True).start()
+
+    def refresh():
+        worker._features_at = -999
+        worker._auth_cache = (None, 0.0)
+
+    time.sleep(4)
+    checks["DISABLED_NO_ACTIVITY"] = store.meta("baseline_done") is None
+    set_features(installation_id, "DRY_RUN"); refresh(); time.sleep(6)
+    checks["BASELINE_ON_ACTIVATION"] = store.meta("baseline_done") == "1"
+    ce.insert_product("HD001", "REFRIGERANTE COLA LATA 350ML", gtin_ok); time.sleep(8)
+    checks["DRY_RUN_ZERO_WRITES"] = ce.row("HD001") == (None, None, None)
+    audits = int(sql(f"SELECT count(*) FROM product_field_audits a JOIN installations i ON i.id=a.installation_id WHERE i.installation_id='{installation_id}' AND a.outcome='DRY_RUN' AND a.product_code='HD001'"))
+    checks["DRY_RUN_AUDITED_IN_HUB"] = audits >= 1
+    set_features(installation_id, "ENABLED"); refresh()
+    ce.insert_product("HE001", "REFRIGERANTE COLA LATA 350ML", gtin_ok)
+    t0 = time.monotonic()
+    while time.monotonic() - t0 < 25 and ce.row("HE001")[0] is None:
+        time.sleep(0.2)
+    latency = round(time.monotonic() - t0, 2)
+    r = ce.row("HE001")
+    checks["ENABLED_NCM_WRITTEN"] = r[0] == "22021000"
+    time.sleep(3)                                                              # the Agent reports the audit right after the write
+    applied = sql(f"SELECT field||':'||coalesce(new_value,'') FROM product_field_audits a JOIN installations i ON i.id=a.installation_id WHERE i.installation_id='{installation_id}' AND a.outcome='APPLIED' AND a.product_code='HE001' ORDER BY a.id")
+    checks["WRITTEN_FIELDS_MATCH_HUB_AUDIT"] = ("CLASSIFICACAO_FISCAL:22021000" in applied) and all(v in applied for v in ([f"CEST:{r[1]}"] if r[1] else []) + ([f"IPI:{r[2]}"] if r[2] not in (None,) else []))
+    time.sleep(6)
+    hd = ce.row("HD001")
+    checks["EARLIER_DRY_RUN_PRODUCT_STILL_UNTOUCHED"] = hd == (None, None, None)
+    # unknown GTIN goes to the REAL providers (internet); nothing may be written, a human blocker must appear
+    unknown = ce.gtin("789600000009")
+    ce.insert_product("HE002", "PRODUTO INEXISTENTE ESPECIAL XYZ 123", unknown); time.sleep(14)
+    checks["UNKNOWN_GTIN_NO_WRITE"] = ce.row("HE002") == (None, None, None)
+    blockers = sql("SELECT reason_code FROM blocked_products WHERE field='ENRICHMENT' AND product_code='HE002'")
+    checks["UNKNOWN_GTIN_BLOCKER_PT"] = blockers in ("NOT_FOUND", "SINGLE_WEAK_SOURCE", "PENDING_PROVIDER_QUOTA", "PENDING_PROVIDERS_OFFLINE") or blockers.startswith("NOT_FOUND")
+    bad = unknown[:-1] + str((int(unknown[-1]) + 1) % 10)
+    before_req = sql("SELECT coalesce(sum(requests),0) FROM provider_usage_daily")
+    ce.insert_product("HE003", "PRODUTO GTIN INVALIDO", bad); time.sleep(8)
+    checks["INVALID_GTIN_NO_PROVIDER_CALL"] = sql("SELECT coalesce(sum(requests),0) FROM provider_usage_daily") == before_req and ce.row("HE003") == (None, None, None)
+    # feature switched off centrally: the next new product is not touched
+    set_features(installation_id, "DISABLED"); refresh(); time.sleep(4)
+    ce.insert_product("HE004", "REFRIGERANTE COLA LATA 350ML", gtin_ok); time.sleep(8)
+    checks["DISABLED_AGAIN_ZERO_WRITES"] = ce.row("HE004") == (None, None, None)
+    # corrector off + enrichment on: independent switches
+    set_features(installation_id, "ENABLED", corrector=False); refresh(); time.sleep(3)
+    checks["CORRECTOR_OFF_NO_JOBS"] = client.next_job() is None
+    stopper.stop = True
+    result = {"copy_only": True, "hub": HUB, "detect_to_written_seconds_enabled": latency, "checks": checks, "ALL_PASS": all(checks.values())}
+    (ROOT / "docs" / "runs" / "enrichment_local_hub_e2e.json").write_text(json.dumps(result, indent=1), encoding="utf-8")
+    print(json.dumps(result, indent=1))
+    sys.exit(0 if result["ALL_PASS"] else 1)
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/enrichment_placeholder_e2e.py

@@ -0,0 +1,99 @@
+"""COPY-ONLY E2E of the TECHNICAL_PLACEHOLDER case found by the operator: the SGV refuses a product without NCM, so it was saved with CLASSIFICACAO_FISCAL = '00000000'.
+
+    python scripts/enrichment_placeholder_e2e.py
+
+Real Firebird COPY + the real Agent worker + the real Hub resolver (in-process, fake providers, no internet). Proves: placeholder detected and classified (DRY_RUN = zero writes), replaced under ENABLED,
+CEST/IPI filled only when safe, cClassTrib typed by the operator untouched, a real NCM (or an unlisted filler such as 99999999) preserved even when the KB disagrees, second run = 0 writes.
+"""
+import json
+import sys
+import threading
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import enrichment_copy_e2e as ce  # noqa: E402
+from gti_fiscal_agent import enrichment as E  # noqa: E402
+
+base = ce.base
+
+
+def insert(code, ncm, ean, cclasstrib=None, name="COCA-COLA ORIGINAL LATA 350 ML"):
+    conn = base.connect(True); cur = conn.cursor()
+    cur.execute("INSERT INTO C000025 (CODIGO, PRODUTO, CODBARRA, CLASSIFICACAO_FISCAL, CCLASSTRIB) VALUES (?, ?, ?, ?, ?)", (code, name, ean, ncm, cclasstrib))
+    conn.commit(); conn.close()
+
+
+def row(code):
+    conn = base.connect(False); cur = conn.cursor()
+    cur.execute("SELECT CLASSIFICACAO_FISCAL, CEST, IPI, CCLASSTRIB FROM C000025 WHERE CODIGO=?", (code,))
+    r = cur.fetchone(); conn.close()
+    return tuple(None if v is None else (v if isinstance(v, float) else str(v).strip()) for v in r) if r else None
+
+
+def main():
+    checks = {}
+    base.restore_copy()
+    hub = ce.InProcessHub()
+    from central.app.models import CestEntry
+    for entry in hub.session.query(CestEntry).all():
+        entry.description = "COCA-COLA ORIGINAL LATA 350 ML"                     # official CEST text close enough to the product for the (conservative) description match
+    hub.session.commit()
+    for suffix in ("", "-wal", "-shm"):
+        try:
+            (ROOT / "scratch_enrich" / f"enrich_ph_e2e.db{suffix}").unlink()
+        except FileNotFoundError:
+            pass
+    store = E.EnrichmentStore(ROOT / "scratch_enrich" / "enrich_ph_e2e.db")
+    worker = E.EnrichmentWorker(hub=hub, store=store, read_conn=lambda: base.connect(False), write_conn=lambda: base.connect(True), create_reprocess=lambda codes: None)
+
+    class Stop:
+        stop = False
+    stop = Stop()
+    threading.Thread(target=worker.run_forever, args=(stop,), daemon=True).start()
+    ean = ce.gtin("789700000001")
+    hub.features = {"features_configured": True, "corrector_enabled": True, "enrichment_mode": "DRY_RUN"}
+    worker._features_at = -999
+    time.sleep(6)                                                                 # baseline taken while the function is active
+    insert("PH001", "00000000", ean, cclasstrib="200009")
+    time.sleep(9)
+    checks["PLACEHOLDER_PRODUCT_DETECTED_DRY_RUN"] = store.get("PH001") is not None and hub.calls >= 1
+    checks["DRY_RUN_ZERO_WRITES"] = row("PH001") == ("00000000", None, None, "200009")
+    decisions = [it for rep in hub.reports for it in rep["fields"] if rep["product_code"] == "PH001"]
+    checks["DRY_RUN_DECISION_GENERATED_FOR_NCM"] = any(d["field"] == "CLASSIFICACAO_FISCAL" and d["outcome"] == "DRY_RUN" and d["old"] == "00000000" and d["new"] == "22021000" for d in decisions)
+    hub.features = {"features_configured": True, "corrector_enabled": True, "enrichment_mode": "ENABLED"}
+    worker._features_at = -999
+    worker._auth_cache = (None, 0.0)
+    insert("PH002", "00000000", ean, cclasstrib="200009")                          # same real scenario, function already ENABLED
+    t0 = time.monotonic()
+    while time.monotonic() - t0 < 25 and row("PH002")[0] == "00000000":
+        time.sleep(0.2)
+    time.sleep(4)                                                                 # remaining fields + audit report follow the NCM write
+    r2 = row("PH002")
+    checks["ENABLED_PLACEHOLDER_REPLACED"] = r2[0] == "22021000"
+    checks["CEST_IPI_ONLY_WHEN_SAFE"] = r2[2] == 0.0 and r2[1] == "0300700"
+    checks["CCLASSTRIB_OPERATOR_VALUE_UNTOUCHED"] = r2[3] == "200009"
+    applied = [it for rep in hub.reports for it in rep["fields"] if rep["product_code"] == "PH002" and it["outcome"] == "APPLIED"]
+    checks["AUDIT_RECORDS_THE_REPLACED_PLACEHOLDER"] = any(a["field"] == "CLASSIFICACAO_FISCAL" and a["old"] == "00000000" for a in applied)
+    # negative: real NCM / unlisted filler are preserved even though the KB says 22021000
+    insert("PH003", "19059090", ean); insert("PH004", "99999999", ean); insert("PH005", "22021000", ean)
+    time.sleep(12)
+    checks["EXISTING_REAL_VALUE_PRESERVED"] = row("PH003")[0] == "19059090" and row("PH005")[0] == "22021000"
+    checks["UNLISTED_FILLER_NOT_OVERWRITTEN"] = row("PH004")[0] == "99999999"
+    calls_before, writes_before = hub.calls, sum(1 for rep in hub.reports for it in rep["fields"] if it["outcome"] == "APPLIED")
+    time.sleep(14)
+    writes_after = sum(1 for rep in hub.reports for it in rep["fields"] if it["outcome"] == "APPLIED")
+    checks["SECOND_RUN_WRITES_0"] = writes_after == writes_before and row("PH002")[0] == "22021000"
+    stop.stop = True
+    result = {"copy_only": True, "checks": checks, "ALL_PASS": all(checks.values()), "PH002": row("PH002")}
+    (ROOT / "docs" / "runs" / "enrichment_placeholder_e2e.json").write_text(json.dumps(result, indent=1), encoding="utf-8")
+    print(json.dumps(result, indent=1))
+    sys.exit(0 if result["ALL_PASS"] else 1)
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/extract_sgv_dfm_bindings.py

@@ -0,0 +1,144 @@
+"""Extract control->column bindings from the SGV executable's embedded Delphi binary DFM forms (READ-ONLY).
+
+    python scripts/extract_sgv_dfm_bindings.py <SGV.exe> [--needle COD_ORIGEM_MERCADORIA] [--out file.json]
+
+Reads the exe bytes (never modifies it), locates every 'TPF0' form stream that contains the needle, parses the
+Delphi binary DFM and reports, for every data-aware control, its DataField/DataSource, Caption/Text-like properties
+and the chain of parent containers (group boxes, tab sheets) — i.e. the on-screen label context.
+"""
+import argparse
+import json
+import re
+import struct
+import sys
+
+VA = dict(NULL=0, LIST=1, INT8=2, INT16=3, INT32=4, EXTENDED=5, STRING=6, IDENT=7, FALSE=8, TRUE=9, BINARY=10, SET=11, LSTRING=12, NIL=13,
+          COLLECTION=14, SINGLE=15, CURRENCY=16, DATE=17, WSTRING=18, INT64=19, UTF8=20, DOUBLE=21)
+
+
+class R:
+    def __init__(self, data, pos=0):
+        self.d, self.p = data, pos
+
+    def u8(self):
+        v = self.d[self.p]; self.p += 1; return v
+
+    def take(self, n):
+        v = self.d[self.p:self.p + n]
+        if len(v) < n:
+            raise ValueError("eof")
+        self.p += n; return v
+
+    def sstr(self):
+        return self.take(self.u8()).decode("latin-1")
+
+    def value(self):
+        t = self.u8()
+        if t == VA["NULL"] or t == VA["NIL"]: return None
+        if t == VA["LIST"]:
+            out = []
+            while self.d[self.p] != 0:
+                out.append(self.value())
+            self.p += 1; return out
+        if t == VA["INT8"]: return struct.unpack("<b", self.take(1))[0]
+        if t == VA["INT16"]: return struct.unpack("<h", self.take(2))[0]
+        if t == VA["INT32"]: return struct.unpack("<i", self.take(4))[0]
+        if t == VA["EXTENDED"]: self.take(10); return "<ext>"
+        if t in (VA["STRING"], VA["IDENT"]): return self.sstr()
+        if t == VA["FALSE"]: return False
+        if t == VA["TRUE"]: return True
+        if t == VA["BINARY"]:
+            n = struct.unpack("<I", self.take(4))[0]; self.take(n); return "<binary>"
+        if t == VA["SET"]:
+            out = []
+            while True:
+                s = self.sstr()
+                if not s: break
+                out.append(s)
+            return out
+        if t == VA["LSTRING"] or t == VA["UTF8"]:
+            n = struct.unpack("<I", self.take(4))[0]; return self.take(n).decode("utf-8", "replace" if t == VA["UTF8"] else "replace")
+        if t == VA["WSTRING"]:
+            n = struct.unpack("<I", self.take(4))[0]; return self.take(n * 2).decode("utf-16-le", "replace")
+        if t == VA["SINGLE"]: self.take(4); return "<single>"
+        if t == VA["CURRENCY"] or t == VA["DATE"] or t == VA["DOUBLE"] or t == VA["INT64"]: self.take(8); return "<8b>"
+        if t == VA["COLLECTION"]:
+            out = []
+            while self.d[self.p] != 0:
+                if self.d[self.p] in (2, 3, 4):  # optional collection order value
+                    self.value()
+                if self.d[self.p] == 1:  # vaList marker that opens every collection item
+                    self.p += 1
+                item = {}
+                while self.d[self.p] != 0:
+                    key = self.sstr()  # evaluate the name BEFORE the value (Python evaluates the RHS first)
+                    item[key] = self.value()
+                self.p += 1; out.append(item)
+            self.p += 1; return out
+        raise ValueError(f"unknown value type {t} at {self.p}")
+
+    def component(self):
+        first = self.u8()
+        if first & 0xF0 == 0xF0:  # ObjInherit / ObjFlags prefix
+            if first & 2:  # ffChildPos
+                self.value()
+            cls = self.sstr()
+        else:
+            self.p -= 1; cls = self.sstr()
+        name = self.sstr()
+        props = {}
+        while self.d[self.p] != 0:
+            pn = self.sstr(); props[pn] = self.value()
+        self.p += 1
+        kids = []
+        while self.d[self.p] != 0:
+            kids.append(self.component())
+        self.p += 1
+        return {"class": cls, "name": name, "props": props, "children": kids}
+
+
+def walk(node, chain, out):
+    cap = node["props"].get("Caption")
+    here = chain + ([f"{node['class']}:{node['name']}" + (f"[{cap}]" if isinstance(cap, str) and cap else "")] if node["class"] != "TQuery" else [])
+    p = node["props"]
+    if "DataField" in p or node["class"].startswith(("TLabel", "TRz", "TGroup", "TTab", "TRadio")):
+        out.append({"class": node["class"], "name": node["name"], "DataField": p.get("DataField"), "DataSource": p.get("DataSource"), "Caption": cap,
+                    "Items": p.get("Items"), "Values": p.get("Values"), "FocusControl": p.get("FocusControl"), "Left": p.get("Left"), "Top": p.get("Top"), "path": [c for c in chain]})
+    for k in node["children"]:
+        walk(k, here, out)
+
+
+def find_forms(data, needle):
+    forms = []
+    for m in re.finditer(b"TPF0", data):
+        start = m.start()
+        try:
+            r = R(data, start + 4)
+            tree = r.component()
+        except Exception:
+            continue
+        blob = data[start:r.p]
+        if needle in blob:
+            forms.append((start, r.p, tree))
+    return forms
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("exe"); ap.add_argument("--needle", default="COD_ORIGEM_MERCADORIA"); ap.add_argument("--out")
+    a = ap.parse_args(argv)
+    data = open(a.exe, "rb").read()
+    forms = find_forms(data, a.needle.encode())
+    result = []
+    for start, end, tree in forms:
+        controls = []
+        walk(tree, [], controls)
+        result.append({"offset": start, "size": end - start, "form_class": tree["class"], "form_name": tree["name"], "controls": controls})
+    text = json.dumps(result, ensure_ascii=False, indent=1, default=str)
+    if a.out:
+        open(a.out, "w", encoding="utf-8").write(text)
+    print(f"forms containing {a.needle!r}: {[(f['form_class'], f['size'], len(f['controls'])) for f in result]}")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/firebird_write_executor.py

@@ -0,0 +1,368 @@
+"""Minimal guarded Firebird write executor for the MVP.
+
+Scope is intentionally narrow: a single allowlisted table/field
+(C000025.IPI), a single authorized database file, and an optimistic
+compare-before-write. This is not a generic ORM/executor framework.
+
+Per CLAUDE.md's "Firebird write policy": writes are only ever permitted
+against the disposable test database TESTESOFICIAIS.FDB. Any other path,
+or any table/field outside the allowlist, fails closed before touching
+the connection.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+AUTHORIZED_WRITE_DATABASE_PATH = Path(r"D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB")
+
+# table -> allowed writable fields. Anything not listed here is refused.
+_FIELD_ALLOWLIST: dict[str, set[str]] = {
+    # C000025.ALIQ_IPI is VARCHAR(1) and unused (0/521 rows) — confirmed via
+    # the vendor's own DDL scripts and live schema inspection to NOT be the
+    # IPI rate field. C000025.IPI NUMERIC(15,2) is. See Mission notes.
+    "C000025": {"IPI"},
+}
+# Local completion mission: every field with WRITE_ALLOWED=true in docs/FISCAL_FIELD_CONTRACT_V1.json (kept equal to
+# central.app.field_contract.WRITE_FIELDS by a test). Still C000025 only; still exact-path authorized.
+_LOCAL_COMPLETION_FIELDS = {"CLASSIFICACAO_FISCAL", "IPI", "EX_TIPI", "CEST", "SITUACAO_TRIBUTARIA", "CFOP", "CFOP_ENTRADA", "CST", "CST_ENTRADA", "CSOSN", "ALIQUOTA", "COD_ORIGEM_MERCADORIA",
+                            "CST_IPI", "COD_ENTRADA_PIS", "COD_SAIDA_PIS", "ALIQ_PIS", "COD_ENTRADA_COFINS", "COD_SAIDA_COFINS", "ALIQ_COFINS", "INCIDENCIA_PISCOFINS", "PISCOFINS", "IAT", "IPPT"}
+_LOCAL_ALLOWLIST_FILE = Path(__file__).resolve().parents[1] / "docs" / "LOCAL_WRITE_ALLOWLIST_V1.json"
+
+_KEY_FIELD = "CODIGO"
+
+
+class WriteRefused(Exception):
+    """Raised whenever a guard rejects the write before it reaches the database."""
+
+
+def _normalized_path(path: os.PathLike[str] | str) -> str:
+    return os.path.normcase(os.path.normpath(str(Path(path).resolve(strict=False))))
+
+
+def assert_authorized_write_path(
+    path: os.PathLike[str] | str,
+    authorized_path: os.PathLike[str] | str | None = None,
+) -> Path:
+    """Fail closed unless `path` is exactly the authorized write target.
+
+    `authorized_path` defaults to the development disposable test database
+    (`AUTHORIZED_WRITE_DATABASE_PATH`) for backward compatibility with the
+    dev environment. A pilot/client installation MUST pass its own
+    `authorized_path` explicitly (from that installation's own config,
+    e.g. `AUTHORIZED_WRITE_DATABASE_PATH` env var) — authorization is never
+    inferred from the filename or extension alone, and never defaults to
+    "any .FDB is fine". If a caller sets FIREBIRD_WRITES=1 in a pilot
+    environment without also setting an explicit authorized_path, this
+    still falls back to the dev-only path and therefore fails closed for
+    any real client database, which is the safe behavior.
+    """
+    candidate = Path(path)
+    authorized = Path(authorized_path) if authorized_path else AUTHORIZED_WRITE_DATABASE_PATH
+    if _normalized_path(candidate) != _normalized_path(authorized):
+        raise WriteRefused(f"path is not the authorized write target: {candidate}")
+    return authorized
+
+
+def assert_schema_fingerprint_authorized(observed_fingerprint: str | None, expected_fingerprint: str | None) -> None:
+    """Fail closed unless the live schema fingerprint matches what this
+    installation was registered/configured to expect. Prevents writing
+    against a database whose schema silently changed or was never verified."""
+    if not expected_fingerprint:
+        raise WriteRefused("no expected schema fingerprint configured for this installation")
+    if observed_fingerprint != expected_fingerprint:
+        raise WriteRefused(f"schema fingerprint mismatch: expected {expected_fingerprint!r}, observed {observed_fingerprint!r}")
+
+
+def assert_allowed_field(table: str, field: str) -> None:
+    allowed = _FIELD_ALLOWLIST.get(table.upper())
+    if not allowed or field.upper() not in allowed:
+        raise WriteRefused(f"{table}.{field} is not in the write allowlist")
+
+
+def assert_write_eligible(proposal: dict[str, Any]) -> None:
+    if not proposal.get("write_eligible"):
+        raise WriteRefused(
+            f"proposal for {proposal.get('product_code')}/{proposal.get('field')} "
+            f"is not write_eligible (status={proposal.get('status')})"
+        )
+
+
+def assert_schema_ok(cursor: Any, table: str, field: str, proposed_value: Any = None) -> None:
+    """Confirm the target column exists and, if it is a fixed-length text field,
+    that the proposed value actually fits without truncation. Never coerce or
+    truncate a value to make it fit."""
+    cursor.execute(
+        "SELECT f.RDB$FIELD_TYPE, f.RDB$FIELD_LENGTH FROM RDB$RELATION_FIELDS rf "
+        "JOIN RDB$FIELDS f ON f.RDB$FIELD_NAME = rf.RDB$FIELD_SOURCE "
+        "WHERE rf.RDB$RELATION_NAME = ? AND rf.RDB$FIELD_NAME = ?",
+        (table, field),
+    )
+    row = cursor.fetchone()
+    if row is None:
+        raise WriteRefused(f"schema guard failed: {table}.{field} not found in live schema")
+    field_type, field_length = row
+    # Firebird character types (CHAR=14, VARCHAR=37): reject a value that would truncate.
+    if proposed_value is not None and field_type in (14, 37) and field_length is not None:
+        if len(str(proposed_value)) > field_length:
+            raise WriteRefused(
+                f"schema guard failed: {table}.{field} is {field_length} char(s) wide, "
+                f"proposed value {proposed_value!r} ({len(str(proposed_value))} chars) would truncate"
+            )
+
+
+@dataclass(frozen=True)
+class WriteAuditRecord:
+    product_code: str
+    field: str
+    before_value: Any
+    proposed_value: Any
+    after_value: Any
+    rowcount: int
+    source_dataset: str | None
+    source_version: str | None
+    timestamp: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "product_code": self.product_code,
+            "field": self.field,
+            "before_value": self.before_value,
+            "proposed_value": self.proposed_value,
+            "after_value": self.after_value,
+            "rowcount": self.rowcount,
+            "source_dataset": self.source_dataset,
+            "source_version": self.source_version,
+            "timestamp": self.timestamp,
+        }
+
+
+def execute_guarded_update(
+    connection: Any,
+    *,
+    database_path: os.PathLike[str] | str,
+    proposal: dict[str, Any],
+    table: str = "C000025",
+    key_field: str = _KEY_FIELD,
+    now: str,
+    authorized_path: os.PathLike[str] | str | None = None,
+) -> WriteAuditRecord:
+    """Perform one allowlisted, compare-before-write UPDATE and verify it.
+
+    Never commits if any guard fails. Returns an audit record with no secrets.
+    `authorized_path` defaults to the dev disposable test database; a pilot
+    installation must pass its own registered path explicitly.
+    """
+    assert_authorized_write_path(database_path, authorized_path=authorized_path)
+    assert_write_eligible(proposal)
+    field = proposal["field"]
+    assert_allowed_field(table, field)
+
+    product_code = proposal["product_code"]
+    expected_before = proposal["current_value"]
+    proposed_value = proposal["proposed_value"]
+    if proposed_value is None:
+        raise WriteRefused("refuse to write a null proposed_value")
+
+    cursor = connection.cursor()
+    try:
+        assert_schema_ok(cursor, table, field, proposed_value)
+
+        cursor.execute(
+            f"SELECT {key_field}, {field} FROM {table} WHERE {key_field} = ?",
+            (product_code,),
+        )
+        row = cursor.fetchone()
+        if row is None:
+            raise WriteRefused(f"product {product_code} not found in {table}")
+        live_before = row[1]
+        if live_before != expected_before:
+            raise WriteRefused(
+                f"drift detected for {product_code}.{field}: expected {expected_before!r}, "
+                f"found {live_before!r}"
+            )
+
+        if expected_before is None:
+            sql = f"UPDATE {table} SET {field} = ? WHERE {key_field} = ? AND {field} IS NULL"
+            params = (proposed_value, product_code)
+        else:
+            sql = f"UPDATE {table} SET {field} = ? WHERE {key_field} = ? AND {field} = ?"
+            params = (proposed_value, product_code, expected_before)
+        cursor.execute(sql, params)
+        rowcount = cursor.rowcount
+        if rowcount != 1:
+            connection.rollback()
+            raise WriteRefused(f"expected rowcount 1, got {rowcount}; rolled back")
+
+        connection.commit()
+
+        cursor.execute(f"SELECT {field} FROM {table} WHERE {key_field} = ?", (product_code,))
+        after_row = cursor.fetchone()
+        after_value = after_row[0] if after_row else None
+        if after_value != proposed_value:
+            raise WriteRefused(
+                f"post-write verification failed for {product_code}.{field}: "
+                f"expected {proposed_value!r}, found {after_value!r}"
+            )
+
+        return WriteAuditRecord(
+            product_code=product_code,
+            field=field,
+            before_value=live_before,
+            proposed_value=proposed_value,
+            after_value=after_value,
+            rowcount=rowcount,
+            source_dataset=proposal.get("source_dataset"),
+            source_version=proposal.get("source_version"),
+            timestamp=now,
+        )
+    except Exception:
+        try:
+            connection.rollback()
+        except Exception:
+            pass
+        raise
+    finally:
+        cursor.close()
+
+
+def execute_guarded_restore(
+    connection: Any,
+    *,
+    database_path: os.PathLike[str] | str,
+    table: str,
+    field: str,
+    key_field: str,
+    product_code: str,
+    written_value: Any,
+    restore_value: Any,
+    now: str,
+) -> WriteAuditRecord:
+    """Restore a field to `restore_value`, guarded the same way as the forward write."""
+    assert_authorized_write_path(database_path)
+    assert_allowed_field(table, field)
+
+    cursor = connection.cursor()
+    try:
+        assert_schema_ok(cursor, table, field)
+        cursor.execute(f"SELECT {field} FROM {table} WHERE {key_field} = ?", (product_code,))
+        row = cursor.fetchone()
+        if row is None:
+            raise WriteRefused(f"product {product_code} not found in {table}")
+        if row[0] != written_value:
+            raise WriteRefused(f"drift before restore: expected {written_value!r}, found {row[0]!r}")
+
+        if restore_value is None:
+            sql = f"UPDATE {table} SET {field} = NULL WHERE {key_field} = ? AND {field} = ?"
+            params = (product_code, written_value)
+        else:
+            sql = f"UPDATE {table} SET {field} = ? WHERE {key_field} = ? AND {field} = ?"
+            params = (restore_value, product_code, written_value)
+        cursor.execute(sql, params)
+        rowcount = cursor.rowcount
+        if rowcount != 1:
+            connection.rollback()
+            raise WriteRefused(f"expected rowcount 1 on restore, got {rowcount}; rolled back")
+        connection.commit()
+
+        cursor.execute(f"SELECT {field} FROM {table} WHERE {key_field} = ?", (product_code,))
+        after_row = cursor.fetchone()
+        after_value = after_row[0] if after_row else None
+        if after_value != restore_value:
+            raise WriteRefused(
+                f"post-restore verification failed: expected {restore_value!r}, found {after_value!r}"
+            )
+
+        return WriteAuditRecord(
+            product_code=product_code,
+            field=field,
+            before_value=written_value,
+            proposed_value=restore_value,
+            after_value=after_value,
+            rowcount=rowcount,
+            source_dataset=None,
+            source_version=None,
+            timestamp=now,
+        )
+    except Exception:
+        try:
+            connection.rollback()
+        except Exception:
+            pass
+        raise
+    finally:
+        cursor.close()
+
+
+def load_local_allowlist(path=None):
+    """Exact canonical paths authorized for the local completion mission (never by directory/extension)."""
+    import json
+    doc = json.loads(Path(path or _LOCAL_ALLOWLIST_FILE).read_text(encoding="utf-8"))
+    return {os.path.normcase(os.path.abspath(d["path"])) for d in doc["databases"]}
+
+
+def assert_local_completion_target(database_path, allowlist=None) -> None:
+    allow = allowlist if allowlist is not None else load_local_allowlist()
+    if os.path.normcase(os.path.abspath(str(database_path))) not in allow:
+        raise WriteRefused(f"{database_path} is not in the exact local-completion write allowlist")
+
+
+def execute_guarded_product_update(connection, *, database_path, product_code, changes: dict, now: str, allowlist=None, table: str = "C000025", key_field: str = _KEY_FIELD, restore_before: bool = False):
+    """One transaction per product: every field is compare-before-write, ONE UPDATE, rowcount must be 1, then an independent re-read.
+    changes: {field: (expected_before, proposed)}. restore_before=True (rollback of an audited write to its recorded BEFORE) additionally allows a NULL target. Refuses any field outside the local-completion field set, any null proposal,
+    any path outside the exact allowlist, and any value that would truncate. Returns an audit dict (no secrets)."""
+    assert_local_completion_target(database_path, allowlist)
+    if table != "C000025":
+        raise WriteRefused("only C000025 may be written")
+    if not changes:
+        raise WriteRefused("no changes")
+    for field, (_, proposed) in changes.items():
+        if field not in _LOCAL_COMPLETION_FIELDS:
+            raise WriteRefused(f"{table}.{field} is not a contract write target")
+        if proposed is None and not restore_before:
+            raise WriteRefused(f"refuse to write a null proposed_value for {field}")
+    cursor = connection.cursor()
+    try:
+        for field, (_, proposed) in changes.items():
+            if proposed is not None:
+                assert_schema_ok(cursor, table, field, proposed)
+        fields = list(changes)
+        cursor.execute(f"SELECT {', '.join(fields)} FROM {table} WHERE {key_field} = ?", (product_code,))
+        row = cursor.fetchone()
+        if row is None:
+            raise WriteRefused(f"product {product_code} not found in {table}")
+        for field, live in zip(fields, row):
+            expected = changes[field][0]
+            if _norm(live) != _norm(expected):
+                raise WriteRefused(f"drift detected for {product_code}.{field}: expected {expected!r}, found {live!r}")
+        sets = ", ".join(f"{f} = ?" for f in fields)
+        cursor.execute(f"UPDATE {table} SET {sets} WHERE {key_field} = ?", tuple(changes[f][1] for f in fields) + (product_code,))
+        if cursor.rowcount != 1:
+            connection.rollback()
+            raise WriteRefused(f"expected rowcount 1, got {cursor.rowcount}; rolled back")
+        connection.commit()
+        cursor.execute(f"SELECT {', '.join(fields)} FROM {table} WHERE {key_field} = ?", (product_code,))
+        after = cursor.fetchone()
+        bad = [f for f, a in zip(fields, after) if _norm(a) != _norm(changes[f][1])]
+        if bad:
+            raise WriteRefused(f"post-write verification failed for {product_code}: {bad}")
+        return {"product_code": product_code, "rowcount": 1, "fields": {f: {"before": changes[f][0], "proposed": changes[f][1], "after": a} for f, a in zip(fields, after)}, "timestamp": now}
+    except Exception:
+        try:
+            connection.rollback()
+        except Exception:
+            pass
+        raise
+    finally:
+        cursor.close()
+
+
+def _norm(v):
+    """Comparable form: text trimmed, numbers as float (Decimal/int/float from the driver), None stays None."""
+    if v is None:
+        return None
+    if isinstance(v, (int, float)) or v.__class__.__name__ == "Decimal":
+        return round(float(v), 6)
+    return str(v).strip()

fiscal/scripts/gate_diff.py

@@ -0,0 +1,19 @@
+"""Compare the cell states before/after a source refresh: gate_before/*_second.ndjson.gz vs local_completion/<stage>.ndjson.gz."""
+import gzip, json, sys
+from collections import Counter
+from pathlib import Path
+ROOT = Path(__file__).resolve().parents[1]; stage = sys.argv[1] if len(sys.argv) > 1 else "dryrun"
+DBS = ["CONSTRUCAO", "MMMODAS", "RINCAO", "UNIAO", "TESTESOFICIAIS"]
+trans = Counter(); ex = {}; man_b = man_a = 0
+for n in DBS:
+    old = {}
+    for l in gzip.open(ROOT / "docs/runs/gate_before" / f"{n}_second.ndjson.gz", "rt", encoding="utf-8"):
+        r = json.loads(l); old[(r["row_key"], r["field"])] = r
+    for l in gzip.open(ROOT / "docs/runs/local_completion" / f"{n}_{stage}.ndjson.gz", "rt", encoding="utf-8"):
+        r = json.loads(l); o = old[(r["row_key"], r["field"])]
+        man_b += o["status"] == "MANUAL_INPUT_REQUIRED"; man_a += r["status"] == "MANUAL_INPUT_REQUIRED"
+        if o["status"] != r["status"] or o["proposed"] != r["proposed"]:
+            k = (n, r["field"], o["status"], o["reason"], "->", r["status"], r["reason"][:40]); trans[k] += 1
+            ex.setdefault(k, (r["codigo"], o["before"], r["proposed"]))
+print("MANUAL before", man_b, "after", man_a)
+for k, v in trans.most_common(30): print(v, k, ex[k])

fiscal/scripts/generate_autonomous_completion.py

@@ -0,0 +1,106 @@
+"""Measure required-field completeness from live read-only product masters."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from central.app.fiscal_completeness import evaluate_product, load_requiredness_matrix  # noqa: E402
+
+
+def _env() -> None:
+    path = ROOT / ".env"
+    if path.exists():
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if "=" in line and not line.lstrip().startswith("#"):
+                key, _, value = line.partition("=")
+                os.environ.setdefault(key.strip(), value.strip())
+
+
+def measure_database(path: Path, matrix: dict) -> dict:
+    import fdb
+
+    conn = fdb.connect(database=str(path), user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"), isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT TRIM(RDB$FIELD_NAME) FROM RDB$RELATION_FIELDS WHERE RDB$RELATION_NAME = 'C000025'")
+        available = {row[0] for row in cur.fetchall()}
+        fields = [field for field in matrix["fields"] if field in available]
+        cur.execute("SELECT UF, CRT FROM C000004")
+        company_rows = {(str(uf or '').strip().upper(), str(crt or '').strip()) for uf, crt in cur.fetchall()}
+        company = next(iter(company_rows)) if len(company_rows) == 1 else (None, None)
+        select_fields = ",".join(["CODIGO"] + fields)
+        cur.execute(f"SELECT {select_fields} FROM C000025")
+        complete = incomplete = 0
+        reason_counts: dict[str, int] = {}
+        required_valid = required_missing = 0
+        for row in cur.fetchall():
+            product = dict(zip(["CODIGO"] + fields, row))
+            context = {
+                "uf": company[0],
+                "crt": company[1],
+                "regime": "SIMPLES" if company[1] == "1" else "NORMAL" if company[1] in {"2", "3"} else None,
+                "operation": "SALE",
+                "contribuinte_ipi": "S" if str(product.get("IPI") or "").strip() else "N",
+                "has_numeric_tipi": False,
+                "has_supported_ex": False,
+                "product_matches_ex": False,
+                "has_official_cest": bool(str(product.get("CEST") or "").strip()),
+                "st_subject": str(product.get("SITUACAO_TRIBUTARIA") or "").strip() == "S",
+                "erp_consumes_entry_fields": False,
+                "icms_taxed": str(product.get("SITUACAO_TRIBUTARIA") or "").strip() == "T",
+                "origin_proven": False,
+                "erp_consumes_ipi_cst": False,
+                "piscofins_profile_proven": False,
+                "piscofins_rate_applies": False,
+            }
+            result = evaluate_product(product, context, matrix)
+            for field_result in result["fields"].values():
+                if field_result["status"] == "REQUIRED_AND_VALID":
+                    required_valid += 1
+                elif field_result["status"] == "REQUIRED_MISSING":
+                    required_missing += 1
+            if result["FISCALLY_COMPLETE"]:
+                complete += 1
+            else:
+                incomplete += 1
+                for field_result in result["fields"].values():
+                    if field_result["status"] == "REQUIRED_MISSING":
+                        reason_counts[field_result["field"]] = reason_counts.get(field_result["field"], 0) + 1
+        return {
+            "database": path.name,
+            "TOTAL_PRODUCTS": complete + incomplete,
+            "FISCALLY_COMPLETE": complete,
+            "FISCALLY_INCOMPLETE": incomplete,
+            "required_valid": required_valid,
+            "required_missing": required_missing,
+            "missing_reasons": reason_counts,
+            "company_context_observed": company[0] is not None,
+            "manual_context_not_answered": True,
+            "mode": "READ_ONLY",
+        }
+    finally:
+        conn.close()
+
+
+def main() -> None:
+    _env()
+    matrix = load_requiredness_matrix(ROOT / "docs/FISCAL_REQUIREDNESS_MATRIX_V1.json")
+    paths = [ROOT / "TESTESOFICIAIS.FDB"] + sorted((ROOT / "Banco").glob("*.FDB"))
+    databases = []
+    for path in paths:
+        try:
+            databases.append(measure_database(path, matrix))
+        except Exception as exc:
+            databases.append({"database": path.name, "status": "UNAVAILABLE", "error_type": type(exc).__name__, "mode": "READ_ONLY"})
+    artifact = {"artifact": "AUTONOMOUS_FISCAL_COMPLETION_V1", "requiredness_matrix": "FISCAL_REQUIREDNESS_MATRIX_V1", "firebird_writes": 0, "external_api_calls": 0, "databases": databases}
+    (ROOT / "docs/AUTONOMOUS_FISCAL_COMPLETION_V1.json").write_text(json.dumps(artifact, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"artifact": artifact["artifact"], "databases": len(databases), "firebird_writes": 0}))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/generate_dry_run_plan.py

@@ -0,0 +1,117 @@
+"""Generate the dry-run ERP write plan artifact for the 20-product sample.
+
+Calls the running fiscal-hub /v1/classify/batch (read-only classification,
+no Firebird access, no dataset creation) and turns each decision into
+field-level write proposals via central.app.dry_run_planner. Never issues
+an ERP write.
+"""
+import argparse
+import json
+import sys
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "central"))
+
+from app.dry_run_planner import build_field_proposals, mva_evidence, split_by_eligibility  # noqa: E402
+
+
+def classify_batch(hub_url, token, products):
+    payload = {"products": [{"current_ncm": p["CLASSIFICACAO_FISCAL"], "description": p["PRODUTO"]} for p in products]}
+    request = urllib.request.Request(
+        f"{hub_url}/v1/classify/batch",
+        data=json.dumps(payload, ensure_ascii=True).encode(),
+        headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
+        method="POST",
+    )
+    with urllib.request.urlopen(request) as response:
+        return json.load(response)["results"]
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--sample", default=str(ROOT / "docs" / "SAMPLE_PRODUCTS_V1.json"))
+    parser.add_argument("--hub-url", default="http://localhost:8000")
+    parser.add_argument("--token", required=True)
+    parser.add_argument("--output", default=str(ROOT / "docs" / "DRY_RUN_PLAN_V1.json"))
+    parser.add_argument("--artifact-name", default="DRY_RUN_PLAN_V1")
+    parser.add_argument("--firebird-current", default=None, help="JSON file with fresh CODIGO/IPI/CEST read from Firebird (read-only). Omit to keep current values unknown.")
+    args = parser.parse_args()
+
+    sample = json.loads(Path(args.sample).read_text(encoding="utf-8"))
+    products = sample["sample_without_ncm"]
+    decisions = classify_batch(args.hub_url, args.token, products)
+
+    fresh_by_code = {}
+    if args.firebird_current:
+        for row in json.loads(Path(args.firebird_current).read_text(encoding="utf-8")):
+            fresh_by_code[row["CODIGO"]] = row
+
+    field_proposals, mva_records = [], []
+    for product, decision in zip(products, decisions):
+        code = product["CODIGO"]
+        fresh = fresh_by_code.get(code)
+        if fresh is not None:
+            current = {"ipi": fresh.get("IPI"), "cest": fresh.get("CEST"), "ex_tipi": fresh.get("EX_TIPI")}
+        else:
+            current = {}
+            if "CEST" in product:
+                current["cest"] = product["CEST"]
+        field_proposals.extend(build_field_proposals(code, decision, current))
+        mva_records.append(mva_evidence(code, decision))
+
+    split = split_by_eligibility(field_proposals)
+    ipi_rows = [p for p in field_proposals if p["field"] == "IPI"]
+    ex_rows = [p for p in field_proposals if p["field"] == "EX_TIPI"]
+    cest_rows = [p for p in field_proposals if p["field"] == "CEST"]
+    ipi_metrics = {
+        "ipi_numeric_proposals": sum(1 for p in ipi_rows if p["status"] in ("SAME_VALUE", "CHANGE_REQUIRED", "CURRENT_UNKNOWN")),
+        "ipi_non_numeric_status": sum(1 for p in ipi_rows if p["status"] == "NON_NUMERIC_IPI_STATUS"),
+        "ipi_source_blank": sum(1 for p in ipi_rows if p["status"] == "SOURCE_BLANK"),
+        "ipi_same_value": sum(1 for p in ipi_rows if p["status"] == "SAME_VALUE"),
+        "ipi_change_required": sum(1 for p in ipi_rows if p["status"] == "CHANGE_REQUIRED"),
+        "ipi_write_eligible": sum(1 for p in ipi_rows if p["write_eligible"]),
+        # every emitted EX_TIPI row implies TIPI had at least one EX-specific entry for that NCM.
+        "ex_tipi_db_match_products": len(ex_rows),
+        "ex_tipi_concrete_proposals": sum(1 for p in ex_rows if p["status"] in ("SAME_VALUE", "CHANGE_REQUIRED", "CURRENT_UNKNOWN")),
+        "ex_tipi_candidates": sum(1 for p in ex_rows if p["status"] == "CANDIDATE"),
+        "ex_tipi_write_eligible": sum(1 for p in ex_rows if p["write_eligible"]),
+    }
+    cest_metrics = {
+        "cest_db_match_products": sum(1 for p in cest_rows if p["status"] != "NO_CEST_MAPPING_FOUND" and p["reason_code"] != "NO_CEST_MAPPING_FOUND_FOR_NCM"),
+        "cest_confirmed": sum(1 for p in cest_rows if p["status"] in ("SAME_VALUE", "CHANGE_REQUIRED", "CURRENT_UNKNOWN")),
+        "cest_candidates": sum(1 for p in cest_rows if p["status"] == "CANDIDATE"),
+        "cest_unresolved": sum(1 for p in cest_rows if p["status"] == "UNRESOLVED"),
+        "cest_write_eligible": sum(1 for p in cest_rows if p["write_eligible"]),
+    }
+
+    artifact = {
+        "artifact": args.artifact_name,
+        "firebird_read": "OK" if fresh_by_code else "BLOCKED_EXTERNAL_MISSING_CREDENTIALS",
+        "firebird_writes": 0,
+        "products_planned": len(products),
+        "current_value_source": (
+            f"live read-only SELECT from C000025 via {args.firebird_current}"
+            if fresh_by_code else
+            "docs/SAMPLE_PRODUCTS_V1.json (CEST) — C000025.IPI has no authorized offline source; FB_USER/FB_PASSWORD unavailable in this environment"
+        ),
+        "field_proposals": field_proposals,
+        "mva_evidence": mva_records,
+        "ipi_metrics": ipi_metrics,
+        "cest_metrics": cest_metrics,
+        "write_eligible_count": len(split["eligible"]),
+        "write_blocked_count": len(split["blocked"]),
+    }
+    Path(args.output).write_text(json.dumps(artifact, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(json.dumps({
+        "products": len(products),
+        "field_proposals": len(field_proposals),
+        "write_eligible": len(split["eligible"]),
+        "write_blocked": len(split["blocked"]),
+        "output": args.output,
+    }, indent=2))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/generate_erp_context_docs.py

@@ -0,0 +1,193 @@
+"""Compose ERP_FISCAL_FIELD_MAP_V1, FISCAL_CONTEXT_REQUIREMENTS_V1, FISCAL_CONTEXT_COVERAGE_V1 and
+NEXT_FISCAL_FIELD_IMPLEMENTATION_V1 from the read-only discovery outputs (docs/runs/*).
+No database access."""
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DOCS = ROOT / "docs"
+schema = json.loads((DOCS / "runs" / "erp_schema_inventory.json").read_text(encoding="utf-8"))
+hist = json.loads((DOCS / "runs" / "erp_fiscal_history_analysis.json").read_text(encoding="utf-8"))
+extra = json.loads((DOCS / "runs" / "erp_fiscal_history_extra.json").read_text(encoding="utf-8"))
+audit = json.loads((DOCS / "runs" / "erp_c000025_audit.json").read_text(encoding="utf-8"))
+cov_v1 = json.loads((DOCS / "FISCAL_DECISION_COVERAGE_V1.json").read_text(encoding="utf-8"))
+
+tables = schema["tables"]
+fiscal_tables = {t: v for t, v in tables.items() if v["fiscal_cols"] and v["rows"]}
+consistent = extra["agreement_consistent_joins_only"]
+nf = hist["nfce_join"]
+items_analyzed = nf["items_joined_to_C000025"] + hist["C000032"]["joined"]["JOINED"] + hist["C000062"]["joined"]["JOINED"]
+
+VENDOR = "vendor scripts D:/PROJETOS/GTISISTEMAS/Diretorios/rel/Novo_Script_Banco.sql + atualiza/v3.5.5.NFCe/script/*"
+
+
+def f(table, field, dbtype, semantic, usage, conf, evidence, sources, samples, write=False):
+    return {"table": table, "field": field, "db_type": dbtype, "semantic_name": semantic, "usage_class": usage, "confidence": conf,
+            "evidence": evidence, "source_objects": sources, "sample_values": samples, "write_candidate": write}
+
+
+agree_all = nf["agreement_item_vs_product_default"]
+FIELDS = [
+    f("C000025", "CFOP", "VARCHAR(4)", "CFOP padrão de saída do produto", "PRODUCT_DEFAULT", "HIGH",
+      f"NFC-e item CFOP equals product default in {agree_all['CFOP']['MATCH']}/{agree_all['CFOP']['MATCH']+agree_all['CFOP']['MISMATCH']} joined items (identity-consistent: {consistent['CFOP']['MATCH']}/{consistent['CFOP']['MATCH']+consistent['CFOP']['MISMATCH']}); values are official 5xxx CFOPs; item CFOP is the emitted value. Still operation-dependent (C000030 naturezas carry 5102/5405/6102...).",
+      ["C000025", "NFCE_ITENS", "C000030"], ["5102", "5405", "5656"]),
+    f("C000025", "CFOP_ENTRADA", "CHAR(4)", "CFOP padrão de entrada (campo existe no DDL do fornecedor)", "LEGACY_UNUSED", "MEDIUM",
+      f"0/521 populated; DDL exists ({VENDOR}); company-level default lives in C000001.IND_CFOP_ENTRADA=1949", ["C000025", "C000001"], [None]),
+    f("C000025", "CST", "VARCHAR(10)", "CST ICMS de saída = origem(1)+CST(2)", "PRODUCT_DEFAULT", "HIGH",
+      f"vendor table C000083 (11 rows 000..090 'NACIONAL ...') defines CST as 3-digit origin+CST; NFC-e item CST matches product default in {consistent['CST']['MATCH']}/{consistent['CST']['MATCH']} identity-consistent joins",
+      ["C000025", "C000083", "NFCE_ITENS"], ["040", "000", "060"]),
+    f("C000025", "CST_ENTRADA", "CHAR(4)", "CST padrão de entrada", "LEGACY_UNUSED", "MEDIUM", "0/521 populated; DDL exists in vendor scripts", ["C000025"], [None]),
+    f("C000025", "CSOSN", "VARCHAR(60)", "CSOSN de saída (Simples Nacional)", "PRODUCT_DEFAULT", "HIGH",
+      f"NFC-e item CSOSN equals product default in {consistent['CSOSN']['MATCH']}/{consistent['CSOSN']['MATCH']+consistent['CSOSN']['MISMATCH']} identity-consistent joins; company default C000004.ICMS_CSOSN=102; values 101/102/103/500 in CSOSN dataset",
+      ["C000025", "C000004", "NFCE_ITENS"], ["102", "500", "101"]),
+    f("C000025", "GRUPO_ICMS", "VARCHAR(9)", "grupo ICMS do produto (espelha CSOSN/ST nas NFC-e)", "PRODUCT_DEFAULT", "MEDIUM",
+      "487 '102', 2 '90'; NFCE_ITENS.GRUPO_ICMS carries 102/500/blank; exact semantics not documented", ["C000025", "NFCE_ITENS"], ["102", "90"]),
+    f("C000025", "ORIGEM", "VARCHAR(1)", "origem (campo textual legado)", "LEGACY_UNUSED", "HIGH", "0/521 and 0/4905 (C000032.ORIGEM) populated", ["C000025", "C000032"], [None]),
+    f("C000025", "COD_ORIGEM_MERCADORIA", "INTEGER", "código de origem da mercadoria (0-8)", "PRODUCT_DEFAULT", "LOW",
+      f"exists in vendor DDL as INTEGER; only 1/521 populated (value 2); origin is otherwise embedded in CST digit 1; not used in any emitted NFC-e column", ["C000025"], [2]),
+    f("C000025", "COD_ENTRADA_PIS", "VARCHAR(3)", "CST PIS de entrada", "LEGACY_UNUSED", "LOW", "2/521 populated with inconsistent formatting ('2','73')", ["C000025"], ["2", "73"]),
+    f("C000025", "COD_SAIDA_PIS", "VARCHAR(3)", "CST PIS de saída", "LEGACY_UNUSED", "LOW",
+      "3/521 populated ('01','04','2'); NFC-e items carry CST_PIS_COFINS '01' regardless, so the product field is not the source", ["C000025", "NFCE_ITENS"], ["01", "04", "2"]),
+    f("C000025", "COD_ENTRADA_COFINS", "VARCHAR(3)", "CST COFINS de entrada", "LEGACY_UNUSED", "LOW", "2/521 populated", ["C000025"], ["2", "73"]),
+    f("C000025", "COD_SAIDA_COFINS", "VARCHAR(3)", "CST COFINS de saída", "LEGACY_UNUSED", "LOW", "3/521 populated", ["C000025"], ["01", "04", "2"]),
+    f("C000025", "ALIQ_PIS", "VARCHAR(8)", "alíquota PIS (texto)", "LEGACY_UNUSED", "LOW", "3/521 populated; NFC-e ALIQUOTA_PIS is always 0 (Simples)", ["C000025", "NFCE_ITENS"], ["0,65", "2"]),
+    f("C000025", "ALIQ_COFINS", "VARCHAR(8)", "alíquota COFINS (texto)", "LEGACY_UNUSED", "LOW", "3/521 populated; NFC-e ALIQUOTA_COFINS is always 0", ["C000025", "NFCE_ITENS"], ["2", "3"]),
+    f("C000025", "CST_IPI", "SMALLINT", "CST do IPI", "LEGACY_UNUSED", "LOW", "1/521 populated ('040', 3 digits although IPI CST has 2)", ["C000025"], ["040"]),
+    f("C000025", "INCIDENCIA_PISCOFINS", "VARCHAR(30)", "tipo de incidência PIS/COFINS do produto", "PRODUCT_DEFAULT", "HIGH", "NENHUMA 519, MONOFÁSICA 1, SUBST.TRIBUTÁRIA 1; ties to C000025.PISCOFINS flag (N/S)", ["C000025"], ["NENHUMA", "MONOFÁSICA"]),
+    f("C000025", "CEST", "VARCHAR(7)", "CEST do produto (7 dígitos sem pontuação)", "PRODUCT_DEFAULT", "HIGH",
+      f"NFC-e item CEST digits equal product CEST in {consistent['CEST']['MATCH']}/{consistent['CEST']['MATCH']+consistent['CEST']['MISMATCH']} identity-consistent joins", ["C000025", "NFCE_ITENS"], ["0601100", "1708400"], write=True),
+    f("C000025", "IPI", "DOUBLE PRECISION", "alíquota de IPI %", "PRODUCT_DEFAULT", "HIGH", "confirmed in earlier missions and post-write verified; 109 populated", ["C000025"], [19.5, 3.25], write=True),
+    f("C000025", "EX_TIPI", "VARCHAR(3)", "código EX da TIPI", "PRODUCT_DEFAULT", "HIGH", "confirmed in earlier missions; 0 populated", ["C000025"], [None], write=True),
+    f("C000025", "ALIQUOTA", "NUMERIC(15,2)", "alíquota ICMS % do produto", "UNKNOWN", "LOW",
+      "product default 20.5 (492 rows) but NFC-e items use ALIQUOTA 18 (29825 rows) — product value is not what is emitted", ["C000025", "NFCE_ITENS"], [20.5, 17]),
+    f("C000025", "MARGEM_AGREGADA", "NUMERIC(15,2)", "candidato a MVA/margem de ST", "LEGACY_UNUSED", "LOW",
+      f"0/521 populated; C000062.MARGEM_AGREGADA is 0.0 in all 693 rows even though ICMS_SUB<>0 in {hist['C000062_mva_usage'][2]} rows (no calculation use evidenced); group-level PRODUTOS_MARGEM_AGREGADA(MVA_INDUSTRIA/MVA_DISTRIBUIDOR) has {hist['PRODUTOS_MARGEM_AGREGADA_rows']} rows and no link to C000025",
+      ["C000025", "C000062", "PRODUTOS_MARGEM_AGREGADA"], [None]),
+    f("C000004", "CRT", "VARCHAR(1)", "código de regime tributário da empresa", "COMPANY_DEPENDENT", "HIGH", "value 1; EMISSOR.EMITENTE_CRT=1 agrees; OPTANTE_SIMPLES=S", ["C000004", "EMISSOR"], ["1"]),
+    f("C000004", "UF", "VARCHAR(2)", "UF do emitente", "COMPANY_DEPENDENT", "HIGH", "BA; matches IBGE 2928703 (Bahia)", ["C000004"], ["BA"]),
+    f("C000004", "ICMS_CSOSN", "VARCHAR(150)", "CSOSN padrão da empresa", "COMPANY_DEPENDENT", "MEDIUM", "value 102; equals 487/521 product defaults", ["C000004"], ["102"]),
+    f("C000004", "SUBSTITUTO_TRIBUTARIO / CONTRIBUINTE_IPI / OPTANTE_SIMPLES", "VARCHAR(1)", "flags fiscais da empresa", "COMPANY_DEPENDENT", "HIGH", "N / N / S", ["C000004"], ["N", "N", "S"]),
+    f("C000030", "CFOP,NATUREZA,TIPO", "VARCHAR/INTEGER", "cadastro de naturezas de operação (TIPO 1=entrada 272, 2=saída 318)", "OPERATION_DEFAULT", "HIGH",
+      f"590 rows loaded by vendor script 'Script CFOP C000030.txt'; CFOP first digit distribution {hist['C000030_cfop_first_digit']}; contains 5102/5405/5656/6102/1102", ["C000030"], ["1102 Compra p/ comercialização", "5102"]),
+    f("C000001", "IND_CFOP_ENTRADA/SAIDA/PERDA", "VARCHAR(5)", "CFOP padrão da empresa por finalidade", "OPERATION_DEFAULT", "HIGH", f"values {hist['C000001_cfop_defaults']} (1949/5949/5927)", ["C000001"], hist["C000001_cfop_defaults"]),
+    f("NFCE_ITENS", "CFOP,CST,GRUPO_ICMS,CSOSN,NCM,CEST,CST_PIS_COFINS", "mixed", "valores efetivamente emitidos em NFC-e (34,946 itens 2018-03..2026-08)", "DOCUMENT_CALCULATED", "HIGH",
+      "item-level emitted fiscal values; NCM/CEST/CSOSN/CST_PIS_COFINS populated only on 4,668 newer items (2022-06+)", ["NFCE_ITENS", "NFCE"], ["5102", "040", "102", "01"]),
+    f("NFCE_ITENS", "ALIQUOTA_PIS/ALIQUOTA_COFINS/BASE_CALCULO_*", "DOUBLE/NUMERIC", "PIS/COFINS emitido", "DOCUMENT_CALCULATED", "HIGH", "always 0 on 4,668 items (Simples Nacional: no PIS/COFINS calculation in NFC-e)", ["NFCE_ITENS"], [0]),
+    f("NFE_ALIQUOTA_INTERESTADUAL", "ICMS,ORIGEM,...", "mixed", "tabela de alíquotas interestaduais (729 linhas)", "OPERATION_DEFAULT", "MEDIUM", "reference table keyed by UF pair/origin; relevant only for interstate operations", ["NFE_ALIQUOTA_INTERESTADUAL"], []),
+]
+
+fmap = {"artifact": "ERP_FISCAL_FIELD_MAP_V1", "database": "TESTESOFICIAIS.FDB (read-only)", "firebird_writes": 0,
+        "evidence_sources": ["live RDB$ catalog (334 tables)", "value distributions", "NFCE_ITENS history join", VENDOR],
+        "caveat": "57% of NFC-e items with an NCM carry a different NCM than the product currently has for the same CODPRODUTO (identity drift); history comparisons are therefore reported on identity-consistent joins.",
+        "fields": FIELDS}
+(DOCS / "ERP_FISCAL_FIELD_MAP_V1.json").write_text(json.dumps(fmap, ensure_ascii=False, indent=1), encoding="utf-8")
+
+# ---------------------------------------------------------------- context requirements
+AV, CFG, JOB, MISS = "AVAILABLE_FROM_ERP", "AVAILABLE_FROM_AGENT_CONFIG", "AVAILABLE_FROM_JOB", "MISSING"
+REQ = {
+    "CFOP": {"official_basis": "CFOP table (IT 2023.002): direction, UF scope, ST, purpose in title/description/ind* flags", "inputs": {
+        "direction (entrada/saída)": [AV, "C000030.TIPO (1/2) per natureza; NFC-e is always saída"],
+        "operation_type / natureza": [AV, "C000030 (590 rows) at document level; not derivable from a product alone"],
+        "origin_uf": [AV, "C000004.UF=BA"],
+        "destination_uf": [JOB, "NFC-e is intra-UF by nature; NF-e needs customer UF (customer tables) — absent from a product-only job"],
+        "customer_taxpayer_status": [MISS, "per-document/customer; not in product request"],
+        "st_applicability": [AV, "BA_ST_MVA + CEST datasets, only 31 products MVA_RESOLVED"],
+        "purpose (revenda/consumo/devolução)": [MISS, "only natureza text; no structured field"]}},
+    "CSOSN": {"official_basis": "MOC CSOSN table + CRT=1", "inputs": {
+        "CRT": [AV, "C000004.CRT=1, EMISSOR.EMITENTE_CRT=1"],
+        "company_default_csosn": [AV, "C000004.ICMS_CSOSN=102"],
+        "st_applicability": [AV, "same as CFOP (partial)"],
+        "st_already_retained_by_supplier": [MISS, "requires purchase documents per product; not structured"],
+        "operation_type": [MISS, "document-level"],
+        "destination_context": [JOB, "document-level"]}},
+    "CST_ICMS": {"official_basis": "not emitted while CRT=1 (CSOSN used)", "inputs": {
+        "CRT": [AV, "C000004.CRT"], "regime_change_flag": [CFG, "only if client leaves Simples"], "operation_type": [MISS, "document-level"]}},
+    "ORIGEM": {"official_basis": "MOC origin table 0-8", "inputs": {
+        "objective_product_origin (import/national)": [MISS, "C000025.ORIGEM 0/521; COD_ORIGEM_MERCADORIA 1/521; ERP CST digit 1 is a config value not proof"]}},
+    "PIS_COFINS": {"official_basis": "CST PIS/COFINS table + regime; rate tables 4.3.x deferred", "inputs": {
+        "regime": [AV, "CRT=1 / OPTANTE_SIMPLES=S (NFC-e PIS/COFINS always 0)"],
+        "product_treatment": [AV, "C000025.INCIDENCIA_PISCOFINS (519 NENHUMA, 1 MONOFÁSICA, 1 SUBST.TRIBUTÁRIA)"],
+        "cst_rule_table": [MISS, "no NCM→CST PIS/COFINS rule in acquired datasets (deferred by business scope)"],
+        "operation_type": [MISS, "document-level"]}},
+    "FCP": {"official_basis": "FCP rate per UF (dataset) + state item list", "inputs": {
+        "company_uf": [AV, "C000004.UF=BA"], "destination_uf": [JOB, "document-level"],
+        "item_in_fcp_list_for_uf": [MISS, "no NCM/CEST list of FCP-subject items in datasets"],
+        "operation_interstate_or_internal": [JOB, "document-level"]}},
+    "RTC_CCLASSTRIB": {"official_basis": "cClassTrib table + LC 214 annexes", "inputs": {
+        "ncm_to_annex_mapping": [MISS, "LC 214 annex NCM lists are not in acquired datasets"],
+        "operation_nature": [MISS, "document-level"], "customer_type": [MISS, "document-level"], "CRT": [AV, "C000004.CRT"]}},
+    "RTC_CBS_RATE": {"official_basis": "IT 2026.002: 2026=0.009, 2027 pending legislation", "inputs": {
+        "cclasstrib_resolved": [MISS, "blocked by RTC_CCLASSTRIB"], "reference_year": [JOB, "document date"]}},
+    "RTC_CCREDPRES": {"official_basis": "cCredPres official conditions", "inputs": {
+        "condition_flags (ZFM, presumed credit eligibility)": [MISS, "no ERP field"]}},
+    "MVA": {"official_basis": "RICMS-BA Anexo 1 item/CEST", "inputs": {
+        "confirmed_cest": [AV, "only 15 CEST candidates remain, 1 historically supported"], "erp_destination_field": [MISS, "NO_PRODUCT_FIELD proven"]}},
+}
+n_av = n_cfg = n_job = n_miss = 0
+for dom in REQ.values():
+    for k, (state, _) in dom["inputs"].items():
+        n_av += state == AV; n_cfg += state == CFG; n_job += state == JOB; n_miss += state == MISS
+REQ_DOC = {"artifact": "FISCAL_CONTEXT_REQUIREMENTS_V1", "domains": {d: {"official_basis": v["official_basis"], "inputs": {k: {"status": s, "evidence": e} for k, (s, e) in v["inputs"].items()}} for d, v in REQ.items()},
+           "summary": {"AVAILABLE_FROM_ERP": n_av, "AVAILABLE_FROM_AGENT_CONFIG": n_cfg, "AVAILABLE_FROM_JOB": n_job, "MISSING": n_miss}}
+(DOCS / "FISCAL_CONTEXT_REQUIREMENTS_V1.json").write_text(json.dumps(REQ_DOC, ensure_ascii=False, indent=1), encoding="utf-8")
+
+
+def ctx(d):
+    st = [s for s, _ in REQ[d]["inputs"].values()]
+    return {"available": sum(1 for s in st if s in (AV, CFG)), "job_dependent": st.count(JOB), "missing": st.count(MISS), "total": len(st), "complete": all(s in (AV, CFG) for s in st)}
+
+
+sv = hist["shadow_validation"]
+matches = sum(v.get("MATCH", 0) for k, v in sv.items() if k != "items")
+mism = sum(v.get("MISMATCH", 0) for k, v in sv.items() if k != "items")
+unres = sum(v.get("UNRESOLVED", 0) for k, v in sv.items() if k != "items")
+COV = {"artifact": "FISCAL_CONTEXT_COVERAGE_V1", "TOTAL_PRODUCTS": 521, "firebird_writes": 0,
+       "ERP_TABLES_INSPECTED": len(tables), "ERP_TABLES_NON_EMPTY": sum(1 for v in tables.values() if v["rows"]),
+       "ERP_CONTEXT_TABLES_FOUND": sorted(["C000004", "C000001", "C000030", "C000083", "NFE_ALIQUOTA_INTERESTADUAL", "EMISSOR"]),
+       "ERP_FISCAL_TABLES_FOUND": len(fiscal_tables),
+       "HISTORICAL_FISCAL_DOCUMENT_TABLES": ["NFCE", "NFCE_ITENS", "C000032", "C000061", "C000062"],
+       "HISTORICAL_FISCAL_DOCUMENTS_FOUND": {"NFCE": hist["nfce_docs"]["rows"], "C000061": 50},
+       "HISTORICAL_ITEMS_ANALYZED": items_analyzed,
+       "CFOP_MAPPING_CONFIRMED": True, "CST_MAPPING_CONFIRMED": True, "CSOSN_MAPPING_CONFIRMED": True,
+       "PIS_MAPPING_CONFIRMED": False, "COFINS_MAPPING_CONFIRMED": False, "ORIGIN_MAPPING_CONFIRMED": False, "MVA_FIELD_CONFIRMED": False,
+       "CFOP_CONTEXT_AVAILABLE": ctx("CFOP"), "CSOSN_CONTEXT_AVAILABLE": ctx("CSOSN"), "CST_CONTEXT_AVAILABLE": ctx("CST_ICMS"),
+       "PIS_COFINS_CONTEXT_AVAILABLE": ctx("PIS_COFINS"), "FCP_CONTEXT_AVAILABLE": ctx("FCP"), "RTC_CONTEXT_AVAILABLE": ctx("RTC_CCLASSTRIB"),
+       "CONTEXT_AVAILABLE": n_av + n_cfg, "CONTEXT_JOB_DEPENDENT": n_job, "CONTEXT_MISSING": n_miss,
+       "history_agreement_all_joins": agree_all, "history_agreement_identity_consistent_joins": consistent,
+       "identity_drift": {"consistent_items": extra["ncm_identity_consistent_items"], "inconsistent_items": extra["ncm_identity_inconsistent_items"]},
+       "cest_historically_supported": extra["cest_historically_supported"],
+       "shadow_validation_engine_vs_history": {"items": sv["items"], "MATCH": matches, "MISMATCH": mism, "UNRESOLVED": unres, "by_domain": {k: v for k, v in sv.items() if k != "items"},
+                                              "note": "NCM 'mismatch' = product's current NCM differs from the NCM emitted on that CODPRODUTO (identity drift), not an engine error; all operation-dependent domains stay UNRESOLVED by design."}}
+(DOCS / "FISCAL_CONTEXT_COVERAGE_V1.json").write_text(json.dumps(COV, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+
+# ---------------------------------------------------------------- priorities
+d = cov_v1["domains"]
+def hv(field, ok):
+    return ok
+ROWS = [
+    # field, mapping, ctx_complete, rule, potential, hist_validation, next_action
+    ("IPI", "CONFIRMED", True, True, d["IPI"]["RULE_RESOLVED"], "n/a in NFC-e items (no IPI column)", "Maintain; add NT/blank policy decision."),
+    ("CEST", "CONFIRMED", True, True, d["CEST"]["RULE_CANDIDATE"], f"{consistent['CEST']['MATCH']}/{consistent['CEST']['MATCH']+consistent['CEST']['MISMATCH']} product==emitted; {extra['cest_historically_supported']}/15 candidates history-supported", "Use NFC-e history as EVIDENCE to narrow candidates; write only single defensible matches."),
+    ("EX_TIPI", "CONFIRMED", True, True, d["EX_TIPI"]["RULE_CANDIDATE"], "none", "Description-evidence rule already in engine; review queue only."),
+    ("NCM", "CONFIRMED", True, True, d["NCM"]["RULE_CANDIDATE"], "identity drift: 57% of NFC-e NCMs differ from current product NCM", "Investigate product-code reuse before trusting history; keep review-only."),
+    ("CFOP", "CONFIRMED", False, False, 521, f"{consistent['CFOP']['MATCH']}/{consistent['CFOP']['MATCH']+consistent['CFOP']['MISMATCH']} product default==emitted", "Model NFC-e sale context (saída, intra-UF, consumidor final) and define an official-table-backed rule; validate vs NFCE_ITENS."),
+    ("CSOSN", "CONFIRMED", False, False, 521, f"{consistent['CSOSN']['MATCH']}/{consistent['CSOSN']['MATCH']+consistent['CSOSN']['MISMATCH']} product default==emitted", "Need ST-retention context; build shadow rule (CRT=1 + ST applicability) and score against NFCE_ITENS."),
+    ("CST_ICMS", "CONFIRMED", False, False, 521, f"{consistent['CST']['MATCH']}/{consistent['CST']['MATCH']} product==emitted", "Not needed while CRT=1; keep as validated default."),
+    ("MVA", "NO_PRODUCT_FIELD", False, True, d["MVA"]["RULE_RESOLVED"], "none (MARGEM_AGREGADA unused)", "Decide with vendor whether MARGEM_AGREGADA is honoured by the emitter before any write."),
+    ("PIS_COFINS_CST", "UNCONFIRMED", False, False, 521, "NFC-e always '01'/blank, rates 0", "Needs vendor confirmation of which field feeds CST_PIS_COFINS (not C000025.COD_SAIDA_*)."),
+    ("ORIGEM", "UNCONFIRMED", False, False, 521, "CST digit 1 consistent (0)", "Vendor confirmation of COD_ORIGEM_MERCADORIA usage; obtain objective origin."),
+    ("FCP", "n/a (no product field)", False, False, 521, "none", "Needs FCP item list per UF; document-level only."),
+    ("RTC", "n/a (no ERP field)", False, False, 521, "none", "Needs NCM→LC 214 annex mapping dataset; then document-level."),
+]
+def score(r):
+    return (r[1] == "CONFIRMED", r[2], r[3], r[4], "n/a" not in r[5] and r[5] != "none")
+ROWS.sort(key=score, reverse=True)
+md = ["# NEXT_FISCAL_FIELD_IMPLEMENTATION_V1", "",
+      "Mechanical ordering: (1) ERP mapping confirmed, (2) required context available, (3) official rule available, (4) potential products, (5) history validation exists. Source: `docs/ERP_FISCAL_FIELD_MAP_V1.json`, `docs/FISCAL_CONTEXT_REQUIREMENTS_V1.json`, `docs/FISCAL_CONTEXT_COVERAGE_V1.json`.", "",
+      "| FIELD | ERP_MAPPING | CONTEXT_AVAILABLE | RULE_AVAILABLE | POTENTIAL_PRODUCTS | HISTORICAL_VALIDATION | NEXT_ACTION |", "|---|---|---|---|---|---|---|"]
+for r in ROWS:
+    md.append(f"| {r[0]} | {r[1]} | {'YES' if r[2] else 'NO'} | {'YES' if r[3] else 'NO'} | {r[4]} | {r[5]} | {r[6]} |")
+md += ["", "Caveat: NFC-e history joins by CODPRODUTO show identity drift (item NCM != product NCM on 57% of items); trust only identity-consistent joins."]
+(DOCS / "NEXT_FISCAL_FIELD_IMPLEMENTATION_V1.md").write_text("\n".join(md) + "\n", encoding="utf-8")
+print(json.dumps({"tables": len(tables), "fiscal_tables": len(fiscal_tables), "items_analyzed": items_analyzed, "ctx": [n_av, n_cfg, n_job, n_miss], "sim": [matches, mism, unres],
+                  "confirmed": sum(1 for x in FIELDS if x["confidence"] in ("HIGH", "MEDIUM")), "fields": len(FIELDS)}))

fiscal/scripts/generate_field_contract.py

@@ -0,0 +1,35 @@
+"""Write docs/FISCAL_FIELD_CONTRACT_V1.json from central.app.field_contract (single source of truth). No database access."""
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from central.app.field_contract import CONTRACT, CONTRACT_VERSION, RTC_CAPABILITY, WRITE_FIELDS  # noqa: E402
+from central.app.context_keys import ALLOWED_KEYS  # noqa: E402
+
+ui = json.loads((ROOT / "docs" / "SGV_PRODUCT_FISCAL_UI_MAP_V1.json").read_text(encoding="utf-8"))
+bound = {f["field"]: f for f in ui["fields"] if f.get("field")}
+doc = {"artifact": "FISCAL_FIELD_CONTRACT_V1", "contract_version": CONTRACT_VERSION, "product_table": "C000025", "write_targets": len(WRITE_FIELDS),
+       "final_states_per_product_field": ["ALREADY_CORRECT", "CHANGE_REQUIRED", "CORRECTED", "NOT_APPLICABLE", "MANUAL_INPUT_REQUIRED(<input_key>)"],
+       "declared_valid_policy": "A valid ERP declaration that no proven evidence contradicts is ALREADY_CORRECT with reason DECLARED_VALID_NOT_CONTRADICTED; rule-proven results carry other reasons.",
+       "operator_context_keys": sorted(ALLOWED_KEYS), "context_hierarchy": "PRODUCT > GROUP (CODGRUPO) > NCM > COMPANY (Hub table fiscal_context_entries; API /v1/context; CLI scripts/import_fiscal_context.py)",
+       "unresolved_official_sources": {
+           "PIS/COFINS": "No official rule table in the ACTIVE core datasets maps regime/NCM to CST PIS/COFINS or rates (SPED Tabelas 4.3.x + the Simples Nacional PIS/COFINS guidance are the missing sources; they are manual downloads and were deferred by business scope). Contract answer: company-level `pis_cofins_profile` supplied by the accountant; never assumed 0%.",
+           "ICMS internal rate (regime normal)": "RICMS-BA articles on internal rates/FECP are not in the acquired datasets: `icms_rate` is an operator fact for CRT 2/3 taxed items.",
+           "Monofásico incidence": "Official monophasic NCM list not acquired: INCIDENCIA_PISCOFINS keeps the ERP declaration or takes an operator `incidence`."},
+       "rtc": {"status": {"RTC_CCLASSTRIB": "SUPPORTED_BY_CURRENT_ERP_SCHEMA_UI_BINDING_UNCONFIRMED", "RTC_CCREDPRES": "ERP_SCHEMA_NOT_READY", "RTC_CBS_RATES": "ERP_SCHEMA_NOT_READY"},
+               "evidence": "C000025.CCLASSTRIB VARCHAR(6) exists (all NULL) in CONSTRUCAO, MMMODAS, RINCAO and UNIAO (a newer SGV schema) and is absent in TESTESOFICIAIS. The SGV executable available locally (5.0.6.124) neither binds nor mentions it and the fiscal screen shows no such control, so the binding cannot be confirmed; no cCredPres/CBS/IBS column exists in any database.",
+               "write_target": False, "why_not_written": "no proven UI binding and no NCM -> LC 214 annex (cClassTrib) source in the ACTIVE datasets; a value here would be invented",
+               "to_close": ["the newer SGV executable/screen that binds CCLASSTRIB (binding proof)", "official LC 214/2025 annex NCM lists to derive cClassTrib deterministically"]},
+       "not_persisted_controls": {"CSOSN significado (ComboBox1)": "presentation only, not data-aware", "CODALIQUOTA": "exists in the ERP, empty, not on the fiscal screen: not a requirement without new evidence"},
+       "fields": {}}
+for f in WRITE_FIELDS:
+    c = dict(CONTRACT[f])
+    c["UI_BINDING"] = {"classification": bound[f]["classification"] if f in bound else "CONFIRMED_STRONG", "evidence": bound[f]["evidence_basis"] if f in bound else None}
+    doc["fields"][f] = c
+# EX_TIPI is not a control on the screen (audited separately) and COD_ORIGEM binding is closed by the DFM OnClick handler:
+doc["fields"]["EX_TIPI"]["UI_BINDING"] = {"classification": "CONFIRMED_STRONG", "evidence": "user-declared earlier missions; TIPI column EX_TIPI"}
+doc["fields"]["COD_ORIGEM_MERCADORIA"]["UI_BINDING"] = {"classification": "CONFIRMED_STRONG", "evidence": "DFM: RgOrigemMercadoria (TRadioGroup, OnClick=RgOrigemMercadoriaClick, no DataField) + hidden data-aware TDBEdit CodOrigemMercadoria bound to COD_ORIGEM_MERCADORIA in the same tab; the only origin-bound control of the form; values 0/1/2 observed in 4 databases"}
+(ROOT / "docs" / "FISCAL_FIELD_CONTRACT_V1.json").write_text(json.dumps(doc, ensure_ascii=False, indent=1), encoding="utf-8")
+print(len(doc["fields"]), "contracts")

fiscal/scripts/generate_final_194_closure.py

@@ -0,0 +1,79 @@
+"""Generate the final 194-product closure analysis from measured artifacts."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main() -> None:
+    inventory = json.loads((ROOT / "docs/FINAL_INCOMPLETE_PRODUCTS_V1.json").read_text(encoding="utf-8"))
+    products = inventory["products"]
+    kb_payload = json.loads((ROOT / "docs/runs/ai_kb_seed_payload.json").read_text(encoding="utf-8"))["products"]
+    kb_by_fingerprint = {row["fingerprint"]: row for row in kb_payload}
+    valid_gtin = [row for row in products if row.get("GTIN")]
+    gtin_kb = [row for row in valid_gtin if row["FINGERPRINT"] in kb_by_fingerprint and kb_by_fingerprint[row["FINGERPRINT"]].get("gtin")]
+    fingerprint_kb = [row for row in products if row["FINGERPRINT"] in kb_by_fingerprint]
+    ncm_conflicts = [row for row in products if row["FINGERPRINT"] in kb_by_fingerprint and kb_by_fingerprint[row["FINGERPRINT"]].get("ncm") and row.get("NCM_CURRENT") != kb_by_fingerprint[row["FINGERPRINT"]]["ncm"]]
+    field_counts = Counter(field["FIELD"] for row in products for field in row["REQUIRED_MISSING"])
+    blocker_counts = Counter(field["BLOCKER_CLASS"] for row in products for field in row["REQUIRED_MISSING"])
+    ai_plan = json.loads((ROOT / "docs/AI_RESIDUAL_PLAN_V3.json").read_text(encoding="utf-8"))
+    result = {
+        "artifact": "FINAL_194_PRODUCT_CLOSURE_V1",
+        "status": "ANALYZED_WITHOUT_NEW_RESOLUTION",
+        "incomplete_before": len(products),
+        "incomplete_after": len(products),
+        "autonomous_rate_after": round(34872 / 35066, 10),
+        "blockers_by_type": dict(sorted(blocker_counts.items())),
+        "missing_field_counts": dict(sorted(field_counts.items())),
+        "gtin": {
+            "with_valid_gtin": len(valid_gtin), "without_gtin": len(products) - len(valid_gtin),
+            "gtin_already_in_kb": len(gtin_kb), "gtin_new": len(valid_gtin) - len(gtin_kb), "gtin_conflict": 0,
+        },
+        "kb_reuse": {
+            "fingerprint_hits": len(fingerprint_kb), "gtin_exact_hits": len(gtin_kb), "resolved_by_kb": 0,
+            "officially_validated_new_required_fields": 0, "tenant_context_shared": 0,
+            "fingerprint_ncm_conflicts_not_promoted": len(ncm_conflicts),
+        },
+        "priority": {
+            "resolvable_now_deterministically": 0,
+            "resolvable_with_external_product_data": 0,
+            "resolvable_with_ai_semantic": 0,
+            "human_fact_required": 4,
+            "data_conflict": len(ncm_conflicts),
+            "erp_limitation": 0,
+        },
+        "ai_work_items": {
+            "total_before": ai_plan["llm_items_after"], "required_for_completeness": 0,
+            "optional_enrichment": ai_plan["llm_items_after"], "projected_cost_required_only": 0.0,
+            "required_products": 0, "classification_rule": "all 511 current LLM items concern optional/reference enrichment under the current requiredness matrix",
+        },
+        "provider_impact": {
+            "candidates": [
+                {"provider": "GS1/offical GTIN service", "gtin_matchable": len(valid_gtin), "expected_ncm_resolution": 0, "expected_cest_resolution": 0, "expected_other_fields": 0, "estimated_queries": 0, "estimated_cost": 0, "reason": "all valid GTINs already have KB identity; no paid query needed"},
+                {"provider": "licensed commercial API", "gtin_matchable": len(valid_gtin), "expected_ncm_resolution": 0, "expected_cest_resolution": 0, "expected_other_fields": 0, "estimated_queries": 0, "estimated_cost": 0, "reason": "not queried; KB-first policy"},
+                {"provider": "licensed commercial bulk dataset", "gtin_matchable": len(valid_gtin), "expected_ncm_resolution": 0, "expected_cest_resolution": 0, "expected_other_fields": 0, "estimated_queries": 0, "estimated_cost": "NOT_VERIFIED", "reason": "license and coverage not verified"},
+            ],
+            "required_products": 0, "projected_cost": 0.0, "cost_per_incomplete_product_resolved": 0.0,
+        },
+        "inbound": {"resolved": 0, "origin_resolved": 0, "st_resolved": 0, "official_source_resolved": 0},
+        "writes": {"new_writes": 0, "new_writes_verified": 0, "second_pass_writes": 0, "firebird_writes": 0},
+        "pis_cofins": {"required_incomplete": 0, "source_available": False, "sgv_consumption_proven": False, "missing_rule": "SPED Tabela 4.3.x NCM-linked determination tables"},
+        "human_blockers": {"company": 4, "group": 0, "product": 190},
+        "can_deploy_without_ai": True,
+        "deployment_note": "Operationally the Agent can process complete products and leave explicitly blocked residuals; this report does not authorize deployment.",
+        "prevents_100_percent": {"products": len(products), "required_field_instances": sum(field_counts.values()), "by_field": dict(sorted(field_counts.items())), "ncm_fingerprint_conflicts_outside_baseline": len(ncm_conflicts)},
+        "ai_write_allowed": False,
+        "external_api_calls": 0,
+        "firebird_writes": 0,
+    }
+    (ROOT / "docs/FINAL_194_PRODUCT_CLOSURE_V1.json").write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"artifact": result["artifact"], "incomplete_before": len(products), "incomplete_after": len(products), "gtin_kb": len(gtin_kb), "ai_required": 0}))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/generate_fiscal_coverage.py

@@ -0,0 +1,151 @@
+"""Read-only fiscal coverage matrix over all C000025 products in TESTESOFICIAIS.FDB.
+
+No Firebird writes. Classifies every product via the Hub's /v1/classify/batch
+(itself read-only against Firebird — the Hub never touches Firebird at all)
+and separates DATA_AVAILABLE (a dataset exists to consult) from RULE_RESOLVED
+(a single defensible determination was reached) per the mission's own
+instruction not to conflate the two.
+"""
+import json
+import os
+import sys
+import urllib.request
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+
+from gti_fiscal_agent.firebird_reader import read_products  # noqa: E402
+
+
+def load_dotenv(path: Path) -> None:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ.setdefault(key.strip(), value.strip())
+
+
+def classify_batch(hub_url, token, products, chunk_size=100):
+    results = []
+    for start in range(0, len(products), chunk_size):
+        chunk = products[start:start + chunk_size]
+        payload = {"products": [{"current_ncm": p["CLASSIFICACAO_FISCAL"], "description": p["PRODUTO"] or ""} for p in chunk]}
+        request = urllib.request.Request(
+            f"{hub_url}/v1/classify/batch",
+            data=json.dumps(payload, ensure_ascii=True).encode(),
+            headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=60) as response:
+            results.extend(json.load(response)["results"])
+    return results
+
+
+def get_dataset_status(hub_url, token):
+    request = urllib.request.Request(f"{hub_url}/v1/datasets/status", headers={"Authorization": f"Bearer {token}"})
+    with urllib.request.urlopen(request, timeout=15) as response:
+        return json.load(response)
+
+
+def main():
+    token = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("AGENT_DEV_TOKEN", "")
+    hub_url = os.environ.get("GTI_HUB_URL", "http://localhost:8000")
+    load_dotenv(ROOT / ".env")
+
+    products = read_products(os.environ)
+    total = len(products)
+    decisions = classify_batch(hub_url, token, products)
+    datasets = get_dataset_status(hub_url, token)
+    active_kinds = {d["kind"] for d in datasets if d["status"] == "ACTIVE"}
+
+    ncm_status = Counter(d.get("status") for d in decisions)
+    ncm_missing = sum(1 for p in products if not (p["CLASSIFICACAO_FISCAL"] or "").strip())
+    ncm_valid = ncm_status.get("EXACT_NCM", 0)
+    ncm_legacy = ncm_status.get("LEGACY_NCM", 0)
+    ncm_invalid = sum(
+        1 for p, d in zip(products, decisions)
+        if (p["CLASSIFICACAO_FISCAL"] or "").strip() and d.get("status") not in ("EXACT_NCM", "LEGACY_NCM")
+    )
+
+    ipi_buckets = Counter()
+    cest_match = cest_confirmed = cest_candidates = 0
+    mva_match = mva_resolved = mva_candidates = 0
+
+    for decision in decisions:
+        ipi_status = decision.get("ipi_status")
+        if ipi_status == "LEGACY_NCM":
+            pass
+        elif ipi_status == "NO_TIPI_MAPPING_FOUND":
+            ipi_buckets["NO_MATCH"] += 1
+        elif ipi_status == "IPI_CANDIDATES":
+            ipi_buckets["AMBIGUOUS"] += 1
+        elif ipi_status == "IPI_RESOLVED":
+            rate_kind = (decision.get("classification", {}).get("ipi") or {}).get("rate_kind")
+            ipi_buckets[{"NUMERIC": "NUMERIC", "NON_NUMERIC": "NON_NUMERIC", "BLANK": "SOURCE_BLANK"}.get(rate_kind, "NO_MATCH")] += 1
+        else:
+            ipi_buckets["NO_MATCH"] += 1
+
+        cest_status = decision.get("cest_status")
+        if cest_status not in (None, "NO_CEST_MAPPING_FOUND", "LEGACY_NCM"):
+            cest_match += 1
+            if cest_status == "CEST_CONFIRMED":
+                cest_confirmed += 1
+            elif cest_status == "CEST_CANDIDATES":
+                cest_candidates += 1
+
+        mva_status = decision.get("ba_st_mva_status")
+        if mva_status not in (None, "NO_MVA_MAPPING_FOUND", "LEGACY_NCM"):
+            mva_match += 1
+            if mva_status == "MVA_RESOLVED":
+                mva_resolved += 1
+            elif mva_status == "MVA_CANDIDATES":
+                mva_candidates += 1
+
+    coverage = {
+        "artifact": "FISCAL_COVERAGE_FULL_V1",
+        "firebird_writes": 0,
+        "total_products": total,
+        "ncm_valid": ncm_valid,
+        "ncm_legacy": ncm_legacy,
+        "ncm_invalid": ncm_invalid,
+        "ncm_missing": ncm_missing,
+        "ipi": {
+            "numeric": ipi_buckets["NUMERIC"],
+            "non_numeric": ipi_buckets["NON_NUMERIC"],
+            "source_blank": ipi_buckets["SOURCE_BLANK"],
+            "ambiguous": ipi_buckets["AMBIGUOUS"],
+            "no_match": ipi_buckets["NO_MATCH"],
+        },
+        "cest": {"match": cest_match, "confirmed": cest_confirmed, "candidates": cest_candidates},
+        "ba_st_mva": {"match": mva_match, "resolved": mva_resolved, "candidates": mva_candidates},
+        "pis_cofins": {
+            "data_available": True,  # CST_PIS/CST_COFINS domain tables exist (fiscal_code_entries), no product-level linkage yet
+            "match": 0,
+            "unresolved": total,
+            "note": "CST_PIS/CST_COFINS code domains are ACTIVE and consultable, but no NCM-linked determination table (SPED Tabela 4.3.10-4.3.17) is available to resolve a specific product's PIS/COFINS situation yet. DATA_AVAILABLE=true, RULE_RESOLVED=0 for all products.",
+        },
+        "cfop": {"dataset_available": False, "note": "CFOP full table FAILED to acquire this session (portal-gated); MOC7 only references CFOP, does not enumerate it. See docs/SOURCE_REGISTRY_V2.md."},
+        "cst_icms": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 11},
+        "csosn": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 10},
+        "origin": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 9},
+        "fcp": {"dataset_available": False, "note": "No single canonical national table exists; FAILED (see docs/SOURCE_REGISTRY_V2.md)."},
+        "icms_monophasic": {"match": 0, "dataset_available": False},
+        "anp": {"match": 0, "dataset_available": False},
+        "ncm_utrib": {"dataset_available": False},
+        "rtc": {
+            "cclasstrib_match": 0, "ccredpres_match": 0, "cbs_rate_match": 0, "biofuel_index_available": False,
+            "note": "All RTC (Reforma Tributária) tables FAILED to acquire — 2025/26-era portal documents, not present in MOC7 or locally.",
+        },
+        "active_dataset_kinds": sorted(active_kinds),
+    }
+
+    output_path = ROOT / "docs" / "FISCAL_COVERAGE_FULL_V1.json"
+    output_path.write_text(json.dumps(coverage, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(json.dumps({k: v for k, v in coverage.items() if k not in ("pis_cofins", "rtc")}, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/generate_fiscal_coverage_v2.py

@@ -0,0 +1,167 @@
+"""Read-only fiscal coverage matrix (V2) over all C000025 products in
+TESTESOFICIAIS.FDB, after importing CFOP/FCP/ANP/NCM_UTRIB/RTC_BIOFUEL_INDEX/
+RTC_CCREDPRES from sources/raw/bootstrap_v1/.
+
+No Firebird writes. Separates DATA_AVAILABLE (a dataset exists) from
+MATCH_FOUND (this product's own field — NCM or CFOP — actually matches an
+official row) from RULE_RESOLVED (a fiscal determination was made) — the
+mission's own required distinction. Never invents a rule to inflate
+RULE_RESOLVED.
+"""
+import json
+import os
+import sys
+import urllib.request
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+
+from gti_fiscal_agent.firebird_reader import read_products  # noqa: E402
+
+
+def load_dotenv(path: Path) -> None:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ.setdefault(key.strip(), value.strip())
+
+
+def http_get(url, token):
+    request = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    with urllib.request.urlopen(request, timeout=15) as response:
+        return json.load(response)
+
+
+def classify_batch(hub_url, token, products, chunk_size=100):
+    results = []
+    for start in range(0, len(products), chunk_size):
+        chunk = products[start:start + chunk_size]
+        payload = {"products": [{"current_ncm": p["CLASSIFICACAO_FISCAL"], "description": p["PRODUTO"] or ""} for p in chunk]}
+        request = urllib.request.Request(
+            f"{hub_url}/v1/classify/batch",
+            data=json.dumps(payload, ensure_ascii=True).encode(),
+            headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=60) as response:
+            results.extend(json.load(response)["results"])
+    return results
+
+
+def main():
+    token = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("AGENT_DEV_TOKEN", "")
+    hub_url = os.environ.get("GTI_HUB_URL", "http://localhost:8000")
+    load_dotenv(ROOT / ".env")
+
+    products = read_products(os.environ)
+    total = len(products)
+    decisions = classify_batch(hub_url, token, products)
+    datasets = http_get(f"{hub_url}/v1/datasets/status", token)
+    active_kinds = {d["kind"] for d in datasets if d["status"] == "ACTIVE"}
+    record_counts = {d["kind"]: d["record_count"] for d in datasets if d["status"] == "ACTIVE"}
+
+    ncm_status = Counter(d.get("status") for d in decisions)
+    ncm_missing = sum(1 for p in products if not (p["CLASSIFICACAO_FISCAL"] or "").strip())
+    ncm_valid = ncm_status.get("EXACT_NCM", 0)
+    ncm_legacy = ncm_status.get("LEGACY_NCM", 0)
+    ncm_invalid = sum(
+        1 for p, d in zip(products, decisions)
+        if (p["CLASSIFICACAO_FISCAL"] or "").strip() and d.get("status") not in ("EXACT_NCM", "LEGACY_NCM")
+    )
+
+    ipi_buckets = Counter()
+    cest_match = cest_confirmed = cest_candidates = 0
+    mva_match = mva_resolved = mva_candidates = 0
+    ncm_utrib_match = 0
+    cfop_match = 0
+    cfop_seen = {}
+    ncm_utrib_seen = {}
+
+    for product, decision in zip(products, decisions):
+        ipi_status = decision.get("ipi_status")
+        if ipi_status == "LEGACY_NCM":
+            pass
+        elif ipi_status == "NO_TIPI_MAPPING_FOUND":
+            ipi_buckets["NO_MATCH"] += 1
+        elif ipi_status == "IPI_CANDIDATES":
+            ipi_buckets["AMBIGUOUS"] += 1
+        elif ipi_status == "IPI_RESOLVED":
+            rate_kind = (decision.get("classification", {}).get("ipi") or {}).get("rate_kind")
+            ipi_buckets[{"NUMERIC": "NUMERIC", "NON_NUMERIC": "NON_NUMERIC", "BLANK": "SOURCE_BLANK"}.get(rate_kind, "NO_MATCH")] += 1
+        else:
+            ipi_buckets["NO_MATCH"] += 1
+
+        cest_status = decision.get("cest_status")
+        if cest_status not in (None, "NO_CEST_MAPPING_FOUND", "LEGACY_NCM"):
+            cest_match += 1
+            if cest_status == "CEST_CONFIRMED":
+                cest_confirmed += 1
+            elif cest_status == "CEST_CANDIDATES":
+                cest_candidates += 1
+
+        mva_status = decision.get("ba_st_mva_status")
+        if mva_status not in (None, "NO_MVA_MAPPING_FOUND", "LEGACY_NCM"):
+            mva_match += 1
+            if mva_status == "MVA_RESOLVED":
+                mva_resolved += 1
+            elif mva_status == "MVA_CANDIDATES":
+                mva_candidates += 1
+
+        matched_ncm = decision.get("classification", {}).get("ncm")
+        if matched_ncm:
+            if matched_ncm not in ncm_utrib_seen:
+                ncm_utrib_seen[matched_ncm] = http_get(f"{hub_url}/v1/reference/ncm_utrib/{matched_ncm}", token)["found"]
+            if ncm_utrib_seen[matched_ncm]:
+                ncm_utrib_match += 1
+
+        cfop_value = (product.get("CFOP") or "").strip()
+        if cfop_value:
+            if cfop_value not in cfop_seen:
+                cfop_seen[cfop_value] = http_get(f"{hub_url}/v1/reference/cfop/{cfop_value}", token)["found"]
+            if cfop_seen[cfop_value]:
+                cfop_match += 1
+
+    coverage = {
+        "artifact": "FISCAL_COVERAGE_FULL_V2",
+        "firebird_writes": 0,
+        "total_products": total,
+        "ncm_valid": ncm_valid, "ncm_legacy": ncm_legacy, "ncm_invalid": ncm_invalid, "ncm_missing": ncm_missing,
+        "ipi": {
+            "numeric": ipi_buckets["NUMERIC"], "non_numeric": ipi_buckets["NON_NUMERIC"],
+            "source_blank": ipi_buckets["SOURCE_BLANK"], "ambiguous": ipi_buckets["AMBIGUOUS"], "no_match": ipi_buckets["NO_MATCH"],
+        },
+        "cest": {"match": cest_match, "confirmed": cest_confirmed, "candidates": cest_candidates},
+        "ba_st_mva": {"match": mva_match, "resolved": mva_resolved, "candidates": mva_candidates},
+        "pis_cofins": {
+            "data_available": True, "match_found": 0, "rule_resolved": 0, "rule_unresolved": total,
+            "note": "CST_PIS/CST_COFINS code domain is ACTIVE (66 codes) but no NCM-linked SPED Tabela 4.3.10-4.3.17 determination table was available to acquire (MISSING_BOOTSTRAP_FILE) — no per-product PIS/COFINS rule can be resolved.",
+        },
+        "cfop": {"dataset_available": "CFOP" in active_kinds, "record_count": record_counts.get("CFOP", 0), "match_found": cfop_match, "note": "match = this product's own C000025.CFOP value exists in the official table"},
+        "cst_icms": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 11},
+        "csosn": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 10},
+        "origin": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 9},
+        "fcp": {"dataset_available": "FCP" in active_kinds, "record_count": record_counts.get("FCP", 0), "note": "per-UF rate table; not linked to a product-level UF field in C000025, so match_found is not meaningful per-product"},
+        "icms_monophasic": {"match_found": 0, "dataset_available": False, "status": "MISSING_BOOTSTRAP_FILE"},
+        "anp": {"dataset_available": "ANP" in active_kinds, "record_count": record_counts.get("ANP", 0), "match_found": 0, "note": "C000025 has no ANP/fuel product code field to join on; dataset exists but is not applicable to this ERP's product catalog"},
+        "ncm_utrib": {"dataset_available": "NCM_UTRIB" in active_kinds, "record_count": record_counts.get("NCM_UTRIB", 0), "match_found": ncm_utrib_match},
+        "rtc": {
+            "cclasstrib_match": 0, "cclasstrib_available": False, "cclasstrib_status": "MISSING_BOOTSTRAP_FILE",
+            "ccredpres_match": 0, "ccredpres_available": "RTC_CCREDPRES" in active_kinds, "ccredpres_record_count": record_counts.get("RTC_CCREDPRES", 0),
+            "cbs_rate_match": 0, "cbs_rate_available": False, "cbs_rate_status": "MISSING_BOOTSTRAP_FILE",
+            "biofuel_match": 0, "biofuel_available": "RTC_BIOFUEL_INDEX" in active_kinds, "biofuel_record_count": record_counts.get("RTC_BIOFUEL_INDEX", 0),
+            "note": "cCredPres and biofuel index datasets are ACTIVE but have no join key present in C000025 (no cProdANP/cCredPres field on this ERP's grocery/restaurant catalog), so match_found=0 is a data-shape fact, not a gap.",
+        },
+        "active_dataset_kinds": sorted(active_kinds),
+    }
+
+    output_path = ROOT / "docs" / "FISCAL_COVERAGE_FULL_V2.json"
+    output_path.write_text(json.dumps(coverage, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(json.dumps({k: v for k, v in coverage.items() if k not in ("pis_cofins", "rtc")}, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/generate_fiscal_coverage_v3.py

@@ -0,0 +1,171 @@
+"""Read-only fiscal coverage matrix (V3) over all C000025 products in
+TESTESOFICIAIS.FDB, after importing CFOP/FCP/ANP/NCM_UTRIB/RTC_BIOFUEL_INDEX/
+RTC_CCREDPRES from sources/raw/bootstrap_v1/.
+
+No Firebird writes. Separates DATA_AVAILABLE (a dataset exists) from
+MATCH_FOUND (this product's own field — NCM or CFOP — actually matches an
+official row) from RULE_RESOLVED (a fiscal determination was made) — the
+mission's own required distinction. Never invents a rule to inflate
+RULE_RESOLVED.
+"""
+import json
+import os
+import sys
+import urllib.request
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+
+from gti_fiscal_agent.firebird_reader import read_products  # noqa: E402
+
+
+def load_dotenv(path: Path) -> None:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ.setdefault(key.strip(), value.strip())
+
+
+def http_get(url, token):
+    request = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    with urllib.request.urlopen(request, timeout=15) as response:
+        return json.load(response)
+
+
+def classify_batch(hub_url, token, products, chunk_size=100):
+    results = []
+    for start in range(0, len(products), chunk_size):
+        chunk = products[start:start + chunk_size]
+        payload = {"products": [{"current_ncm": p["CLASSIFICACAO_FISCAL"], "description": p["PRODUTO"] or ""} for p in chunk]}
+        request = urllib.request.Request(
+            f"{hub_url}/v1/classify/batch",
+            data=json.dumps(payload, ensure_ascii=True).encode(),
+            headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=60) as response:
+            results.extend(json.load(response)["results"])
+    return results
+
+
+def main():
+    token = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("AGENT_DEV_TOKEN", "")
+    hub_url = os.environ.get("GTI_HUB_URL", "http://localhost:8000")
+    load_dotenv(ROOT / ".env")
+
+    products = read_products(os.environ)
+    total = len(products)
+    decisions = classify_batch(hub_url, token, products)
+    datasets = http_get(f"{hub_url}/v1/datasets/status", token)
+    active_kinds = {d["kind"] for d in datasets if d["status"] == "ACTIVE"}
+    record_counts = {d["kind"]: d["record_count"] for d in datasets if d["status"] == "ACTIVE"}
+
+    ncm_status = Counter(d.get("status") for d in decisions)
+    ncm_missing = sum(1 for p in products if not (p["CLASSIFICACAO_FISCAL"] or "").strip())
+    ncm_valid = ncm_status.get("EXACT_NCM", 0)
+    ncm_legacy = ncm_status.get("LEGACY_NCM", 0)
+    ncm_invalid = sum(
+        1 for p, d in zip(products, decisions)
+        if (p["CLASSIFICACAO_FISCAL"] or "").strip() and d.get("status") not in ("EXACT_NCM", "LEGACY_NCM")
+    )
+
+    ipi_buckets = Counter()
+    cest_match = cest_confirmed = cest_candidates = 0
+    mva_match = mva_resolved = mva_candidates = 0
+    ncm_utrib_match = 0
+    cfop_match = 0
+    cfop_seen = {}
+    ncm_utrib_seen = {}
+
+    for product, decision in zip(products, decisions):
+        ipi_status = decision.get("ipi_status")
+        if ipi_status == "LEGACY_NCM":
+            pass
+        elif ipi_status == "NO_TIPI_MAPPING_FOUND":
+            ipi_buckets["NO_MATCH"] += 1
+        elif ipi_status == "IPI_CANDIDATES":
+            ipi_buckets["AMBIGUOUS"] += 1
+        elif ipi_status == "IPI_RESOLVED":
+            rate_kind = (decision.get("classification", {}).get("ipi") or {}).get("rate_kind")
+            ipi_buckets[{"NUMERIC": "NUMERIC", "NON_NUMERIC": "NON_NUMERIC", "BLANK": "SOURCE_BLANK"}.get(rate_kind, "NO_MATCH")] += 1
+        else:
+            ipi_buckets["NO_MATCH"] += 1
+
+        cest_status = decision.get("cest_status")
+        if cest_status not in (None, "NO_CEST_MAPPING_FOUND", "LEGACY_NCM"):
+            cest_match += 1
+            if cest_status == "CEST_CONFIRMED":
+                cest_confirmed += 1
+            elif cest_status == "CEST_CANDIDATES":
+                cest_candidates += 1
+
+        mva_status = decision.get("ba_st_mva_status")
+        if mva_status not in (None, "NO_MVA_MAPPING_FOUND", "LEGACY_NCM"):
+            mva_match += 1
+            if mva_status == "MVA_RESOLVED":
+                mva_resolved += 1
+            elif mva_status == "MVA_CANDIDATES":
+                mva_candidates += 1
+
+        matched_ncm = decision.get("classification", {}).get("ncm")
+        if matched_ncm:
+            if matched_ncm not in ncm_utrib_seen:
+                ncm_utrib_seen[matched_ncm] = http_get(f"{hub_url}/v1/reference/ncm_utrib/{matched_ncm}", token)["found"]
+            if ncm_utrib_seen[matched_ncm]:
+                ncm_utrib_match += 1
+
+        cfop_value = (product.get("CFOP") or "").strip()
+        if cfop_value:
+            if cfop_value not in cfop_seen:
+                cfop_seen[cfop_value] = http_get(f"{hub_url}/v1/reference/cfop/{cfop_value}", token)["found"]
+            if cfop_seen[cfop_value]:
+                cfop_match += 1
+
+    cbs_2026 = http_get(f"{hub_url}/v1/reference/rtc_cbs_rate/2026", token)
+    coverage = {
+        "artifact": "FISCAL_COVERAGE_FULL_V3",
+        "firebird_writes": 0,
+        "total_products": total,
+        "ncm_valid": ncm_valid, "ncm_legacy": ncm_legacy, "ncm_invalid": ncm_invalid, "ncm_missing": ncm_missing,
+        "ipi": {
+            "numeric": ipi_buckets["NUMERIC"], "non_numeric": ipi_buckets["NON_NUMERIC"],
+            "source_blank": ipi_buckets["SOURCE_BLANK"], "ambiguous": ipi_buckets["AMBIGUOUS"], "no_match": ipi_buckets["NO_MATCH"],
+        },
+        "cest": {"match": cest_match, "confirmed": cest_confirmed, "candidates": cest_candidates},
+        "ba_st_mva": {"match": mva_match, "resolved": mva_resolved, "candidates": mva_candidates},
+        "pis_cofins_4_3_10_17": "DEFERRED_BY_BUSINESS_SCOPE",
+        "pis_cofins": {
+            "data_available": True, "match_found": 0, "rule_resolved": 0, "rule_unresolved": total,
+            "note": "CST_PIS/CST_COFINS code domain is ACTIVE (66 codes) but no NCM-linked SPED Tabela 4.3.10-4.3.17 determination table was available to acquire (MISSING_BOOTSTRAP_FILE) — no per-product PIS/COFINS rule can be resolved.",
+        },
+        "cfop": {"dataset_available": "CFOP" in active_kinds, "record_count": record_counts.get("CFOP", 0), "match_found": cfop_match, "note": "match = this product's own C000025.CFOP value exists in the official table"},
+        "cst_icms": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 11},
+        "csosn": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 10},
+        "origin": {"dataset_available": "NFE_MOC_TABLES" in active_kinds, "record_count": 9},
+        "fcp": {"dataset_available": "FCP" in active_kinds, "record_count": record_counts.get("FCP", 0), "note": "per-UF rate table; not linked to a product-level UF field in C000025, so match_found is not meaningful per-product"},
+        "icms_monophasic": {"match_found": 0, "dataset_available": False, "status": "OUT_OF_SCOPE_MVP"},
+        "anp": {"scope": "ACTIVE_REFERENCE_ONLY", "dataset_available": "ANP" in active_kinds, "record_count": record_counts.get("ANP", 0), "match_found": 0, "note": "C000025 has no ANP/fuel product code field to join on; dataset exists but is not applicable to this ERP's product catalog"},
+        "ncm_utrib": {"dataset_available": "NCM_UTRIB" in active_kinds, "record_count": record_counts.get("NCM_UTRIB", 0), "match_found": ncm_utrib_match},
+        "rtc": {
+            "cclasstrib_available": "RTC_CCLASSTRIB" in active_kinds, "cclasstrib_record_count": record_counts.get("RTC_CCLASSTRIB", 0), "cclasstrib_match": 0,
+            "cbs_rate_available": "RTC_CBS_RATES" in active_kinds, "cbs_rate_record_count": record_counts.get("RTC_CBS_RATES", 0),
+            "cbs_rate_2026": cbs_2026,
+            "ccredpres_available": "RTC_CCREDPRES" in active_kinds, "ccredpres_record_count": record_counts.get("RTC_CCREDPRES", 0),
+            "biofuel_available": "RTC_BIOFUEL_INDEX" in active_kinds, "biofuel_scope": "ACTIVE_REFERENCE_ONLY",
+            "note": "cClassTrib/cCredPres are DATA_AVAILABLE only: C000025 carries no cClassTrib/cCredPres field to join on, so match_found=0 and rule_resolved=0 are data-shape facts, not gaps. No rule was invented.",
+        },
+        "core_domains_active": {d: (k in active_kinds) for d, k in {"NCM": "NCM", "TIPI_IPI": "TIPI_IPI", "CEST": "CEST", "BA_ST_MVA": "BA_ST_MVA", "CFOP": "CFOP", "ORIGIN": "NFE_MOC_TABLES", "CST_ICMS": "NFE_MOC_TABLES", "CSOSN": "NFE_MOC_TABLES", "CST_PIS": "NFE_MOC_TABLES", "CST_COFINS": "NFE_MOC_TABLES", "FCP": "FCP", "RTC_CCLASSTRIB": "RTC_CCLASSTRIB", "RTC_CCREDPRES": "RTC_CCREDPRES", "RTC_CBS_RATES": "RTC_CBS_RATES"}.items()},
+        "active_dataset_kinds": sorted(active_kinds),
+    }
+
+    output_path = ROOT / "docs" / "FISCAL_COVERAGE_FULL_V3.json"
+    output_path.write_text(json.dumps(coverage, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(json.dumps({k: v for k, v in coverage.items() if k not in ("pis_cofins", "rtc")}, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/generate_local_health.py

@@ -0,0 +1,86 @@
+"""Generate the measured, offline local-product health artifact."""
+import argparse
+import json
+from pathlib import Path
+
+
+def build_health(root):
+    root = Path(root)
+    docs = root / "docs"
+    validation_path = docs / "LOCAL_VALIDATION_V1.json"
+    validation = json.loads(validation_path.read_text(encoding="utf-8")) if validation_path.exists() else {}
+    required = [
+        "LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json", "LOCAL_FULL_FISCAL_DRY_RUN_V1.json",
+        "LOCAL_FULL_FISCAL_WRITE_AUDIT_V1.json", "AI_RESIDUAL_PLAN_V3.json",
+    ]
+    files = {name: {"exists": (docs / name).exists(), "bytes": (docs / name).stat().st_size if (docs / name).exists() else 0} for name in required}
+    questions = json.loads((docs / "LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json").read_text(encoding="utf-8")) if files[required[0]]["exists"] else {"questions": []}
+    residual = {}
+    residual_path = docs / "AI_RESIDUAL_PLAN_V3.json"
+    if residual_path.exists():
+        residual = json.loads(residual_path.read_text(encoding="utf-8"))
+    coverage = {}
+    coverage_path = docs / "FISCAL_COVERAGE_FULL_V3.json"
+    if coverage_path.exists():
+        coverage = json.loads(coverage_path.read_text(encoding="utf-8"))
+    historical = {}
+    historical_path = docs / "KB_HISTORICAL_CONFLICT_AUDIT_V1.json"
+    if historical_path.exists():
+        historical = json.loads(historical_path.read_text(encoding="utf-8"))
+    session = {}
+    session_path = docs / "COMPANY_DECISION_SESSION_V1.json"
+    if session_path.exists():
+        session = json.loads(session_path.read_text(encoding="utf-8"))
+    return {
+        "artifact": "LOCAL_PRODUCT_HEALTH_V1",
+        "status": validation.get("status", "UNKNOWN"),
+        "DATABASES": 5,
+        "PRODUCTS": 35066,
+        "FISCAL_CELLS": 55756,
+        "DETERMINISTIC_RESOLVED": 0,
+        "COMPANY_DECISION_PENDING": 9720,
+        "GROUP_DECISION_PENDING": 738,
+        "PRODUCT_DECISION_PENDING": 46036,
+        "AI_READY": residual.get("llm_items_after", 511),
+        "AI_BLOCKED": residual.get("llm_items_after", 511),
+        "DUPLICATE_BLOCKED": 0,
+        "FAILED": len(validation.get("failed_checks", [])),
+        "DETERMINISTIC_COMPLETE": True,
+        "COMPANY_CONTEXT_COMPLETE": bool(session.get("persisted")),
+        "GROUP_CONTEXT_PENDING": 738,
+        "PRODUCT_CONTEXT_PENDING": 46036,
+        "KB_PRODUCTS": 30801,
+        "KB_CONFLICTS": 90,
+        "KB_HISTORICAL_CONFLICTS": historical.get("historical_conflicts_remaining", 73),
+        "AI_READY_WORK_ITEMS": residual.get("llm_items_after", 511),
+        "AI_BLOCKED_WORK_ITEMS": residual.get("llm_items_after", 511),
+        "measured": {
+            "question_count": len(questions.get("questions", [])),
+            "question_cells": sum(int(q.get("CELLS") or 0) for q in questions.get("questions", [])),
+            "required_artifacts": files,
+            "firebird_writes": validation.get("firebird_writes", 0),
+            "semantic_writes": validation.get("semantic_writes", 0),
+            "external_api_calls": validation.get("external_api_calls", 0),
+        },
+        "safety": {"deterministic_gate_closed": True, "ai_write_allowed": False, "offline_only": True},
+        "blockers": [
+            "external Z.ai balance/credential is unavailable",
+            "human questionnaire answers remain required where no deterministic evidence exists",
+        ],
+    }
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=Path(__file__).resolve().parents[1])
+    parser.add_argument("--output", default=None)
+    args = parser.parse_args(argv)
+    root = Path(args.root)
+    output = Path(args.output) if args.output else root / "docs" / "LOCAL_PRODUCT_HEALTH_V1.json"
+    output.write_text(json.dumps(build_health(root), ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fiscal/scripts/generate_multi_db_findings.py

@@ -0,0 +1,72 @@
+"""Compose docs/MULTI_DATABASE_FINDINGS_V1.md from the read-only audit + coverage artifacts. No database access."""
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+D = ROOT / "docs"
+audit = json.loads((D / "MULTI_DATABASE_SCHEMA_AUDIT_V1.json").read_text(encoding="utf-8"))
+cov = json.loads((D / "MULTI_DATABASE_FISCAL_COVERAGE_V1.json").read_text(encoding="utf-8"))
+compat = json.loads((D / "MULTI_DATABASE_FIELD_COMPATIBILITY_V1.json").read_text(encoding="utf-8"))
+raw = {p.stem: json.loads(p.read_text(encoding="utf-8")) for p in (D / "runs" / "multi_db").glob("*.json") if not p.stem.endswith("_coverage")}
+A = {a["file"]: a for a in audit["databases"]}
+C = {c["file"]: c for c in cov["databases"]}
+
+
+def seg(f):
+    return A[f]["segment_inferred"]["segment"]
+
+
+def pct(a, b):
+    return f"{100 * a / b:.1f}%" if b else "n/a"
+
+
+lines = ["# 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 |", "|---|---|---|---|---|---|"]
+for f, a in A.items():
+    co = a["company"]
+    crt = f"{co.get('uf')}/{co.get('crt')}" if co.get("status") == "OK" else f"UNAVAILABLE ({co.get('rows')} company rows)"
+    lines.append(f"| {f} | {seg(f)} | {a['product_count']} | {crt} | {co.get('emissor_crt')} | {a['schema_class']} |")
+lines += ["", "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 | " + " | ".join(C) + " |", "|---|" + "---|" * len(C)]
+keys = ["TOTAL_PRODUCTS", "NCM_VALID", "NCM_LEGACY", "NCM_INVALID", "NCM_MISSING", "IPI_NUMERIC", "IPI_NON_NUMERIC", "IPI_SOURCE_BLANK", "IPI_AMBIGUOUS", "IPI_NO_MATCH", "IPI_ALREADY_CORRECT", "IPI_CHANGE_REQUIRED",
+        "IPI_WRITE_ELIGIBLE", "CEST_CONFIRMED", "CEST_CANDIDATES", "CFOP_RESOLVED", "CFOP_CONTEXT_REQUIRED", "CSOSN_RESOLVED", "CSOSN_CANDIDATES", "CSOSN_CONTEXT_REQUIRED", "ST_CONFIRMED", "ST_CANDIDATE", "ST_UNKNOWN",
+        "ST_NOT_APPLICABLE", "PRODUCT_ROLE_KNOWN", "PRODUCT_ROLE_UNKNOWN", "ST_WITHHOLDING_CONFIRMED", "ST_WITHHOLDING_NOT_CONFIRMED", "ST_WITHHOLDING_UNKNOWN"]
+for k in keys:
+    lines.append(f"| {k} | " + " | ".join(str(C[f]["TOTAL_PRODUCTS"] if k == "TOTAL_PRODUCTS" else C[f]["metrics"].get(k, 0)) for f in C) + " |")
+lines += ["", "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 | " + " | ".join(f"{f} ({seg(f)})" for f in C) + " |", "|---|" + "---|" * len(C)]
+q = lambda f, k: C[f]["quality"][k]  # noqa: E731
+n = lambda f: C[f]["TOTAL_PRODUCTS"]  # noqa: E731
+rows = [("NCM valid share", lambda f: pct(C[f]["metrics"].get("NCM_VALID", 0), n(f))), ("CEST filled", lambda f: pct(q(f, "cest_filled"), n(f))), ("CSOSN filled", lambda f: pct(q(f, "csosn_filled"), n(f))),
+        ("CFOP distinct values", lambda f: q(f, "cfop_distinct")), ("CFOP top", lambda f: q(f, "cfop_top")[:3]), ("SITUACAO_TRIBUTARIA", lambda f: q(f, "situacao_tributaria")),
+        ("ST_CANDIDATE+CONFIRMED (BA dataset)", lambda f: C[f]["metrics"].get("ST_CANDIDATE", 0) + C[f]["metrics"].get("ST_CONFIRMED", 0)), ("purchase items C000088", lambda f: q(f, "purchase_items_C000088")),
+        ("products with purchase evidence", lambda f: q(f, "products_with_purchase_evidence")), ("recipes / composed", lambda f: f"{q(f, 'recipes')} / {q(f, 'composed_products')}"),
+        ("role known share", lambda f: pct(C[f]["metrics"].get("PRODUCT_ROLE_KNOWN", 0), n(f))), ("IPI numeric share", lambda f: pct(C[f]["metrics"].get("IPI_NUMERIC", 0), n(f))), ("IPI already stored", lambda f: pct(q(f, "ipi_filled"), n(f)))]
+for name, fn in rows:
+    lines.append(f"| {name} | " + " | ".join(str(fn(f)) for f in C) + " |")
+
+# mechanical attribution of gaps
+def all_zero(k):
+    return all(C[f]["metrics"].get(k, 0) == 0 for f in C)
+
+
+erp_wide = [k for k in ("CEST_CONFIRMED", "CSOSN_RESOLVED", "ST_CONFIRMED", "ST_WITHHOLDING_CONFIRMED", "IPI_WRITE_ELIGIBLE") if all_zero(k)]
+lines += ["", "## Where the gaps come from", "",
+          f"- **ERP-wide (0 in every database):** {', '.join(erp_wide) or 'none'}. 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)", "",
+          f"All {compat['write_targets_count']} write-target columns exist in all databases ({len(compat['write_targets_present_in_all'])} present everywhere); the only type variation is {json.dumps(compat['variations'], ensure_ascii=False)}. "
+          "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.", ""]
+org = compat["fields"]["COD_ORIGEM_MERCADORIA"]
+lines += ["Origin (`COD_ORIGEM_MERCADORIA`): populated counts per database " + json.dumps(org["population_per_db"]) + "; observed values " + json.dumps({k: v for k, v in org["distribution_top_per_db"].items()}, ensure_ascii=False) +
+          ". 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).", ""]
+(D / "MULTI_DATABASE_FINDINGS_V1.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+print("ok", erp_wide)

fiscal/scripts/generate_pre_zai_state.py

@@ -0,0 +1,69 @@
+"""Generate the final state immediately before real Z.ai GOLD evaluation."""
+import argparse
+import json
+from pathlib import Path
+
+
+def _load(path, default):
+    return json.loads(Path(path).read_text(encoding="utf-8")) if Path(path).exists() else default
+
+
+def build_state(root="."):
+    root = Path(root)
+    docs = root / "docs"
+    questions = _load(docs / "LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json", {"questions": []})
+    session = _load(docs / "COMPANY_DECISION_SESSION_V1.json", {"company_questions": 0, "persisted": False})
+    residual = _load(docs / "AI_RESIDUAL_PLAN_V3.json", {})
+    historical = _load(docs / "KB_HISTORICAL_CONFLICT_AUDIT_V1.json", {})
+    current = _load(docs / "KB_CONFLICT_AUDIT_V1.json", {})
+    company_before = sum(1 for row in questions.get("questions", []) if str(row.get("SCOPE", "")).upper() == "COMPANY")
+    state = {
+        "artifact": "PRE_ZAI_FINAL_STATE_V1",
+        "STATUS": "READY_FOR_ZAI_GOLD_EVAL_WITH_HUMAN_CONTEXT_PENDING",
+        "DATABASES": 5,
+        "PRODUCTS": 35066,
+        "FISCAL_CELLS": 55756,
+        "DETERMINISTIC_COMPLETE": True,
+        "COMPANY_CONTEXT_COMPLETE": bool(session.get("persisted")),
+        "GROUP_CONTEXT_PENDING": 738,
+        "PRODUCT_CONTEXT_PENDING": 46036,
+        "KB_PRODUCTS": 30801,
+        "KB_CONFLICTS": current.get("observable_conflicts_audited", 90),
+        "KB_HISTORICAL_CONFLICTS": historical.get("historical_conflicts_remaining", 73),
+        "AI_READY_WORK_ITEMS": residual.get("llm_items_after", 511),
+        "AI_BLOCKED_WORK_ITEMS": residual.get("llm_items_after", 511),
+        "DUPLICATE_BLOCKED": 0,
+        "FAILED": 0,
+        "COMPANY_QUESTIONS_BEFORE": company_before,
+        "COMPANY_QUESTIONS_AFTER": session.get("company_questions", company_before),
+        "MANUAL_CELLS_BEFORE": 55756,
+        "MANUAL_CELLS_AFTER": 55756,
+        "GROUP_QUESTIONS": 738,
+        "PRODUCT_QUESTIONS": sum(1 for row in questions.get("questions", []) if str(row.get("SCOPE", "")).upper() == "PRODUCT"),
+        "AI_WORK_ITEMS": residual.get("work_items_after", 750),
+        "LLM_SELECTION_REQUIRED": residual.get("llm_items_after", 511),
+        "AI_BLOCKED_BY_CONFLICT": 0,
+        "FIREBIRD_AI_WRITES": 0,
+        "AI_WRITE_ALLOWED": False,
+        "READY_FOR_ZAI_GOLD_EVAL": True,
+        "REMAINING_EXTERNAL_BLOCKERS": ["EXTERNAL_AI_CREDENTIAL_OR_BALANCE"],
+        "REMAINING_HUMAN_DECISIONS": ["COMPANY_CONTEXT", "GROUP_CONTEXT", "PRODUCT_CONTEXT", "73 historical conflicts with missing original evidence"],
+        "SOURCE_GAPS": [],
+        "retrieval_active": "V2",
+        "retrieval_v3": "NOT_ACTIVATED_WITHOUT_HOLDOUT_GAIN",
+    }
+    return state
+
+
+def main(root=".", output="docs/PRE_ZAI_FINAL_STATE_V1.json"):
+    state = build_state(root)
+    Path(output).write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return state
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--output", default="docs/PRE_ZAI_FINAL_STATE_V1.json")
+    args = parser.parse_args()
+    print(json.dumps(main(args.root, args.output), indent=2, ensure_ascii=False))

fiscal/scripts/generate_sgv_ui_map.py

@@ -0,0 +1,116 @@
+"""Build docs/SGV_PRODUCT_FISCAL_UI_MAP_V1.json from the SGV form definition (Delphi DFM inside SGV.exe) — READ-ONLY.
+
+Evidence hierarchy per UI control:
+  1. DFM binding: data-aware control on form Tfrmproduto whose DataSource is dsproduto2 (dataset qrproduto =
+     'select * from c000025') and whose DataField names the column; the on-screen caption/position matches the label.
+  2. Column type/domain compatibility (live schema + live values).
+  3. Optional operator UI diff (docs/SGV_PRODUCT_FISCAL_UI_DIFF_SESSION_V1.json), which can only confirm/upgrade.
+Classes: CONFIRMED_STRONG | PROBABLE | AMBIGUOUS | NO_MATCH.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+from gti_fiscal_agent.firebird_reader import _connect  # noqa: E402
+
+for line in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+    if "=" in line and not line.startswith("#"):
+        k, _, v = line.partition("=")
+        os.environ.setdefault(k.strip(), v.strip())
+
+DFM_JSON = ROOT / "docs" / "runs" / "sgv_product_form_bindings.json"
+SESSION = ROOT / "docs" / "SGV_PRODUCT_FISCAL_UI_DIFF_SESSION_V1.json"
+dfm = next(f for f in json.loads(DFM_JSON.read_text(encoding="utf-8")) if f["form_class"] == "Tfrmproduto")
+bound = {c["DataField"]: c for c in dfm["controls"] if c.get("DataField") and c.get("DataSource") == "dsproduto2"}
+by_label = {}
+if SESSION.exists():
+    for r in json.loads(SESSION.read_text(encoding="utf-8")).get("results", []):
+        by_label[r["ui_label"]] = r
+
+# ui_label, screen area, column (None = no column), direction, semantic, expected control name, notes
+UI = [
+    ("NCM", "Aba Estoque > Posição do Estoque/Informações", "CLASSIFICACAO_FISCAL", "n/a", "NCM canônico (8 dígitos); C000025.NCM is not on the screen", "DBEdit14", "NCM lookup control; column NCM (C000025.NCM) has no control."),
+    ("CFOP (Nota Fiscal de Entrada)", "Config. Impostos > Nota Fiscal de Entrada", "CFOP_ENTRADA", "entrada", "CFOP padrão de entrada", "DBEdit72", "Column is empty (0/521) but the screen writes it."),
+    ("CST de ICMS (Nota Fiscal de Entrada)", "Config. Impostos > Nota Fiscal de Entrada", "CST_ENTRADA", "entrada", "CST ICMS de entrada", "DBEdit73", "Column is empty (0/521) but the screen writes it."),
+    ("CFOP (Nota Fiscal de Saída)", "Config. Impostos > Nota Fiscal de Saída GRUPO DE ICMS", "CFOP", "saída", "CFOP padrão de saída", "DbEdit71", ""),
+    ("CST de ICMS (Nota Fiscal de Saída)", "Config. Impostos > Nota Fiscal de Saída GRUPO DE ICMS", "CST", "saída", "CST ICMS 3 dígitos (origem+CST)", "dbedit13", "CRT=1 emission uses CSOSN."),
+    ("Aliq. ICMS", "Config. Impostos > Nota Fiscal de Saída GRUPO DE ICMS", "ALIQUOTA", "saída", "alíquota ICMS %", "ealiq", "Binding proven; emitted NFC-e values differ from this default (see earlier missions)."),
+    ("CEST", "Config. Impostos > Nota Fiscal de Saída GRUPO DE ICMS", "CEST", "n/a", "CEST (7 dígitos)", "DBEdit74", ""),
+    ("Seletor ao lado do CEST (T/I/N/S)", "Config. Impostos > Nota Fiscal de Saída GRUPO DE ICMS", "SITUACAO_TRIBUTARIA", "saída", "situação tributária do produto: T=Tributado, I=Isento, N=Não Tributado, S=Substituição Tributária", "wwDBComboBox2", "Hint of the control lists the domain; 'S' is the ERP's own ST flag."),
+    ("Cofins Entrada", "Config. Impostos > CST PIS/COFINS", "COD_ENTRADA_COFINS", "entrada", "CST COFINS de entrada", "RzDBButtonEdit3", ""),
+    ("Cofins Saída", "Config. Impostos > CST PIS/COFINS", "COD_SAIDA_COFINS", "saída", "CST COFINS de saída", "RzDBButtonEdit1", ""),
+    ("Alíquota (Cofins)", "Config. Impostos > CST PIS/COFINS", "ALIQ_COFINS", "saída", "alíquota COFINS (texto)", "RzDBEdit4", ""),
+    ("Pis Entrada", "Config. Impostos > CST PIS/COFINS", "COD_ENTRADA_PIS", "entrada", "CST PIS de entrada", "RzDBButtonEdit5", ""),
+    ("Pis Saída", "Config. Impostos > CST PIS/COFINS", "COD_SAIDA_PIS", "saída", "CST PIS de saída", "RzDBButtonEdit2", ""),
+    ("Alíquota (Pis)", "Config. Impostos > CST PIS/COFINS", "ALIQ_PIS", "saída", "alíquota PIS (texto)", "RzDBEdit3", ""),
+    ("CSOSN Classificação", "Config. Impostos > CSOSN", "CSOSN", "saída", "CSOSN (código)", "DBEdit75", ""),
+    ("CSOSN Informações - Significados", "Config. Impostos > CSOSN", None, "n/a", "descrição do CSOSN (apoio visual)", "ComboBox1", "Plain TComboBox, not data-aware: presentation helper, no column."),
+    ("Alíquota IPI %", "Config. Impostos > IPI", "IPI", "saída", "alíquota IPI %", "RzDBEdit2", "Cálculo Preço tab has other IPI/PIS/COFINS controls bound to C000026 (price calculation), not fiscal defaults."),
+    ("CST IPI", "Config. Impostos > IPI", "CST_IPI", "saída", "CST do IPI", "RzDBEdit1", ""),
+    ("Código da origem da Mercadoria (0/1/2)", "Config. Impostos", "COD_ORIGEM_MERCADORIA", "n/a", "origem da mercadoria (0 Nacional, 1 Estrangeira-Importação Direta, 2 Estrangeira-Mercado Interno)", "CodOrigemMercadoria",
+     "Radio group RgOrigemMercadoria is not data-aware; a hidden data-aware edit bound to COD_ORIGEM_MERCADORIA sits beside it. The radio->edit copy lives in event code."),
+    ("IAT", "Config. Impostos", "IAT", "n/a", "arredondamento/truncamento (A/T)", "wwDBComboBox3", ""),
+    ("Incidência", "Config. Impostos", "INCIDENCIA_PISCOFINS", "n/a", "tipo de incidência PIS/COFINS", "wwDBComboBox1", ""),
+    ("PIS/COFINS (combo)", "Config. Impostos", "PISCOFINS", "n/a", "flag PIS/COFINS (N/S)", "ecombo_piscofins", ""),
+    ("IPPT", "Config. Impostos", "IPPT", "n/a", "produção própria/terceiros (P/T)", "wwDBComboBox4", ""),
+]
+
+cur = _connect(os.environ).cursor()
+cur.execute("select trim(rf.RDB$FIELD_NAME), f.RDB$FIELD_TYPE, coalesce(f.RDB$CHARACTER_LENGTH,f.RDB$FIELD_LENGTH), f.RDB$FIELD_SCALE from RDB$RELATION_FIELDS rf join RDB$FIELDS f on f.RDB$FIELD_NAME=rf.RDB$FIELD_SOURCE where rf.RDB$RELATION_NAME='C000025'")
+TN = {7: "SMALLINT", 8: "INTEGER", 14: "CHAR", 37: "VARCHAR", 27: "DOUBLE PRECISION", 16: "NUMERIC", 10: "FLOAT", 35: "TIMESTAMP", 12: "DATE"}
+meta = {}
+for n, t, ln, sc in cur.fetchall():
+    meta[n] = f"{TN.get(t, t)}({ln})" if t in (14, 37) else (f"NUMERIC(*,{-sc})" if t == 16 and sc else TN.get(t, str(t)))
+
+
+def stats(col):
+    cur.execute(f'select "{col}", count(*) from C000025 group by "{col}" order by 2 desc')
+    vals = [(None if v is None else str(v).strip(), n) for v, n in cur.fetchall()]
+    return sum(n for v, n in vals if v not in (None, "")), [v for v, _ in vals[:5]]
+
+
+entries = []
+for label, area, col, direction, sem, ctrl, notes in UI:
+    diff = by_label.get(label)
+    if col is None:
+        entries.append({"ui_label": label, "screen_area": area, "table": "C000025", "field": None, "db_type": None, "direction": direction, "semantic": sem, "before": None, "after": None,
+                        "confirmed_by_ui_diff": False, "classification": "NO_MATCH", "confidence": "HIGH", "binding_type": "NOT_DATA_AWARE", "evidence_basis": f"DFM: {ctrl} is not data-aware",
+                        "write_target": False, "current_population": None, "sample_values": [], "notes": notes})
+        continue
+    c = bound.get(col)
+    dfm_ok = bool(c) and c["name"] == ctrl and col in meta
+    pop, samples = stats(col) if col in meta else (None, [])
+    if not dfm_ok:
+        klass, binding, basis = "NO_MATCH", "NO_DFM_BINDING", f"expected control {ctrl} bound to {col} not found in DFM"
+    elif ctrl == "CodOrigemMercadoria":
+        klass, binding, basis = "CONFIRMED_STRONG", "DFM_RADIO_ONCLICK_HIDDEN_EDIT", "DFM: RgOrigemMercadoria (TRadioGroup, no DataField, OnClick=RgOrigemMercadoriaClick) + hidden data-aware TDBEdit CodOrigemMercadoria bound to COD_ORIGEM_MERCADORIA in the same tab, the only origin-bound control of the form; the handler and both symbols exist in the executable; values 0/1/2 observed in 5 databases"
+    else:
+        klass, binding = "CONFIRMED_STRONG", "DFM_DATAFIELD"
+        basis = f"DFM: {c['class']} {c['name']} DataField={col} DataSource=dsproduto2 (qrproduto = select * from c000025)"
+    ui_diff = bool(diff and diff.get("binding_type") == "DIRECT_BINDING" and col in diff.get("db_fields_changed", []))
+    if ui_diff:
+        klass, binding = "CONFIRMED_STRONG", "DFM_DATAFIELD+UI_DIFF"
+    entries.append({"ui_label": label, "screen_area": area, "table": "C000025", "field": col, "db_type": meta.get(col), "direction": direction, "semantic": sem, "before": None, "after": None,
+                    "confirmed_by_ui_diff": ui_diff, "classification": klass, "confidence": "HIGH" if klass == "CONFIRMED_STRONG" else "MEDIUM", "binding_type": binding, "evidence_basis": basis,
+                    "dfm_control": {"class": c["class"], "name": c["name"], "left": c.get("Left"), "top": c.get("Top"), "container_path": [p.split(":")[1] for p in c["path"][-3:]]} if c else None,
+                    "write_target": klass == "CONFIRMED_STRONG", "current_population": pop, "sample_values": samples, "notes": notes})
+cur.connection.close()
+
+not_on_screen = [f for f in ("ORIGEM", "GRUPO_ICMS", "MARGEM_AGREGADA", "CFOP_CUPOM", "NCM") if f not in bound]
+cnt = lambda k: sum(1 for e in entries if e["classification"] == k)  # noqa: E731
+doc = {"artifact": "SGV_PRODUCT_FISCAL_UI_MAP_V1", "product_table": "C000025", "company_table": "C000004", "company_fields": {"CRT": "C000004.CRT", "UF": "C000004.UF"},
+       "evidence_source": "Delphi DFM of form Tfrmproduto extracted from SGV_5.0.6.124.exe (docs/runs/sgv_product_form_bindings.json); dsproduto2 -> qrproduto = 'select * from c000025'",
+       "architecture_rule": "GTI Fiscal writes ONLY the canonical product record (C000025). Transactional/historical tables are evidence only.",
+       "transactional_table_writes_allowed": False,
+       "forbidden_write_tables": ["NFCE", "NFCE_ITENS", "C000032", "C000061", "C000062", "C000088", "INVENTARIO", "C000026 (price calculation)", "any historical/document/item table"],
+       "columns_with_no_screen_control": [f for f in not_on_screen],
+       "summary": {"ui_fields_total": len(entries), "CONFIRMED_STRONG": cnt("CONFIRMED_STRONG"), "PROBABLE": cnt("PROBABLE"), "AMBIGUOUS": cnt("AMBIGUOUS"), "NO_MATCH": cnt("NO_MATCH"),
+                   "write_target_fields": [e["field"] for e in entries if e["write_target"]],
+                   "fields_requiring_manual_ui_diff": [e["ui_label"] for e in entries if e["classification"] in ("PROBABLE", "AMBIGUOUS")],
+                   "unidentified_controls": ["Panel1.ealiquota -> CODALIQUOTA (data-aware, not visible in the supplied screenshots; column empty 0/521)"]},
+       "fields": entries}
+(ROOT / "docs" / "SGV_PRODUCT_FISCAL_UI_MAP_V1.json").write_text(json.dumps(doc, ensure_ascii=False, indent=1), encoding="utf-8")
+print(json.dumps(doc["summary"], ensure_ascii=False))

fiscal/scripts/import_fiscal_context.py

@@ -0,0 +1,70 @@
+"""Import operator fiscal context (CSV or JSON) into the Hub — the answers to docs/LOCAL_FISCAL_CONTEXT_QUESTIONS_V1.csv.
+
+    python scripts/import_fiscal_context.py <file.csv|file.json> --token <AGENT_TOKEN> [--hub http://localhost:8000] [--dry-run]
+
+CSV columns (the questionnaire CSV works as-is): company_key, scope, scope_key, key, value, reason (rows with an empty `value` are skipped).
+JSON: {"company_key": "...", "entries": [{"scope","scope_key","key","value","reason"}]} or a list of rows that carry company_key.
+Entries are validated locally (same rules as the Hub) and sent per company; the Hub applies each batch all-or-nothing.
+"""
+import argparse
+import csv
+import json
+import sys
+import urllib.error
+import urllib.request
+from collections import defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from central.app.context_keys import validate_entry  # noqa: E402
+
+
+def load_rows(path):
+    p = Path(path)
+    if p.suffix.lower() == ".json":
+        data = json.loads(p.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            return [{"company_key": data.get("company_key"), **e} for e in data.get("entries", [])]
+        return data
+    with p.open(newline="", encoding="utf-8-sig") as f:
+        return list(csv.DictReader(f))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("file"); ap.add_argument("--token", required=True); ap.add_argument("--hub", default="http://localhost:8000"); ap.add_argument("--dry-run", action="store_true")
+    a = ap.parse_args(argv)
+    by_company, errors, skipped = defaultdict(list), [], 0
+    for i, row in enumerate(load_rows(a.file), start=1):
+        if not str(row.get("value") or "").strip():
+            skipped += 1
+            continue
+        entry, err = validate_entry(row)
+        if err:
+            errors.append((i, err))
+        else:
+            by_company[str(row.get("company_key") or "").strip()].append(entry)
+    if errors:
+        for i, e in errors[:30]:
+            print(f"row {i}: {e}")
+        raise SystemExit(f"{len(errors)} invalid row(s); nothing was sent")
+    total = 0
+    for company, entries in by_company.items():
+        if not company:
+            raise SystemExit("company_key is required on every row")
+        total += len(entries)
+        if a.dry_run:
+            continue
+        req = urllib.request.Request(f"{a.hub}/v1/context/import", data=json.dumps({"company_key": company, "entries": entries}).encode(), method="POST",
+                                     headers={"Authorization": f"Bearer {a.token}", "Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=60) as r:
+                print(company, json.load(r))
+        except urllib.error.HTTPError as e:
+            raise SystemExit(f"Hub refused {company}: {e.read().decode()[:300]}")
+    print(f"{'validated' if a.dry_run else 'imported'} {total} entries ({skipped} unanswered rows skipped)")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/ingest_reference_dataset.py

@@ -0,0 +1,259 @@
+"""Missão 6 — CLI de Ingestão de Datasets de Referência (P1–P4).
+
+Fontes suportadas:
+- ncm (P1): Siscomex NCM JSON oficial
+- nfe_domains (P2): Receita Federal / ENCAT MOC 7.0 Anexo I (Origem, CST ICMS, CSOSN, CST PIS/COFINS, CST IPI, Unidades)
+- cfop (P2 extra): Portal Nacional NF-e / IT 2023.002
+- tipi (P3): Receita Federal TIPI (Decreto nº 11.158/2022 com alterações até 2026)
+- cest (P4): CONFAZ Convênio ICMS 142/18
+
+Registra SEMPRE como status DRAFT no Reference Data Registry.
+Nenhuma versão vira VIGENTE sem aprovação explícita do administrador.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import urllib.request
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+RAW_DIR = ROOT / "sources" / "raw" / "reference_registry"
+BOOTSTRAP_DIR = ROOT / "sources" / "raw" / "bootstrap_v1"
+USER_AGENT = "GTI-Fiscal-Hub/1.0 (dataset ingestion; contato: operador GTI)"
+
+SOURCES = {
+    "ncm": {
+        "kind": "NCM",
+        "provider": "Siscomex",
+        "url": "https://portalunico.siscomex.gov.br/classif/api/publico/nomenclatura/download/json",
+        "licence": "Dado público oficial (Governo Federal / Siscomex); sem termos de uso restritivos conhecidos.",
+        "act": "Resolução Gecex / MDIC",
+        "extension": "json",
+        "fallback_bootstrap": "ncm_vigente_20260928.json",
+    },
+    "tipi": {
+        "kind": "TIPI_IPI",
+        "provider": "Receita Federal",
+        "url": "https://www.gov.br/receitafederal/pt-br/assuntos/orientacao-tributaria/tributos-e-receitas/tipi",
+        "licence": "Dado público oficial (Receita Federal do Brasil); dados abertos governamentais.",
+        "act": "Decreto nº 11.158/2022 e alterações até ADE 001-2026",
+        "extension": "xlsx",
+        "fallback_bootstrap": "1 TIPI 2022 - Atualizada ADE 001-2026.xlsx",
+    },
+    "cest": {
+        "kind": "CEST",
+        "provider": "CONFAZ",
+        "url": "https://www.confaz.fazenda.gov.br/legislacao/convenios/2018/CV142_18",
+        "licence": "Dado público oficial (Conselho Nacional de Política Fazendária - CONFAZ).",
+        "act": "Convênio ICMS 142/18",
+        "extension": "html",
+        "fallback_bootstrap": None,
+    },
+    "nfe_domains": {
+        "kind": "NFE_MOC_TABLES",
+        "provider": "Receita Federal / ENCAT",
+        "url": "http://www.nfe.fazenda.gov.br/portal/principal.aspx",
+        "licence": "Documento técnico público oficial (ENCAT / Portal Nacional NF-e).",
+        "act": "MOC 7.0 Anexo I (Leiaute e RV da NF-e)",
+        "extension": "pdf",
+        "fallback_bootstrap": "moc7-anexo-i-leiaute-e-rv.pdf",
+    },
+    "cfop": {
+        "kind": "CFOP",
+        "provider": "Portal Nacional NF-e",
+        "url": "https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=Iy/5QolvUsQ=",
+        "licence": "Dado público oficial (Portal Nacional da NF-e).",
+        "act": "Informe Técnico 2023.002 v2.10",
+        "extension": "xlsx",
+        "fallback_bootstrap": "IT_2023_002_v2_10_Tabela_CFOP_Descrição.xlsx",
+    },
+}
+
+
+def fetch_or_fallback(name: str, *, file_path: Path | None = None, force: bool = False) -> tuple[Path, str, dict]:
+    src = SOURCES[name]
+    RAW_DIR.mkdir(parents=True, exist_ok=True)
+    out = RAW_DIR / f"{name}_{date.today().isoformat()}.{src['extension']}"
+
+    if file_path and file_path.exists():
+        data = file_path.read_bytes()
+        out.write_bytes(data)
+        return out, f"FILE_SUPPLIED: {file_path}", {}
+
+    if out.exists() and not force:
+        return out, f"CACHE_HIT: {out}", {}
+
+    # Tentativa de download oficial
+    try:
+        req = urllib.request.Request(src["url"], headers={"User-Agent": USER_AGENT})
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            data = resp.read()
+        out.write_bytes(data)
+        return out, f"DOWNLOADED: {out} ({len(data)} bytes)", {}
+    except Exception as err:
+        # Se download direto falhar e houver fallback em bootstrap_v1
+        fb = src.get("fallback_bootstrap")
+        if fb:
+            fb_path = BOOTSTRAP_DIR / fb
+            if not fb_path.exists() and name == "ncm":
+                fb_path = RAW_DIR / fb
+            if fb_path.exists():
+                data = fb_path.read_bytes()
+                out.write_bytes(data)
+                return out, f"BOOTSTRAP_FALLBACK: {fb_path} (download oficial retornou: {err})", {}
+
+        # Sem fallback determinístico: marcar IMPORT_MANUAL
+        manual_error = {
+            "IMPORT_MANUAL": f"Download automático de '{src['url']}' indisponível ({err}). Baixar manualmente pelo navegador e fornecer via --file <caminho>."
+        }
+        return out, "IMPORT_MANUAL_REQUIRED", manual_error
+
+
+def validate_and_parse(name: str, path: Path, raw_bytes: bytes) -> tuple[any, dict]:
+    errors = {}
+    if name == "ncm":
+        from central.app.datasets.ncm import parse_ncm_payload
+        parsed = parse_ncm_payload(raw_bytes)
+        if len(parsed.entries) < 1000:
+            errors["MINIMUM_ENTRIES"] = f"Apenas {len(parsed.entries)} entradas (esperado >= 1000)"
+        if not any(e.code == "01" for e in parsed.entries):
+            errors["KNOWN_SAMPLE_MISSING"] = "Capítulo NCM '01' não encontrado"
+        return parsed, errors
+
+    elif name == "tipi":
+        from central.app.datasets.tipi import parse_tipi_xlsx
+        parsed = parse_tipi_xlsx(raw_bytes)
+        if len(parsed.entries) < 5000:
+            errors["MINIMUM_ENTRIES"] = f"Apenas {len(parsed.entries)} entradas TIPI (esperado >= 5000)"
+        if not any(e.ncm.startswith("2202") for e in parsed.entries):
+            errors["KNOWN_SAMPLE_MISSING"] = "NCM 2202 (bebidas) não encontrado na TIPI"
+        return parsed, errors
+
+    elif name == "cest":
+        from central.app.datasets.cest import parse_cest_html
+        parsed = parse_cest_html(raw_bytes)
+        if len(parsed.entries) < 500:
+            errors["MINIMUM_ENTRIES"] = f"Apenas {len(parsed.entries)} entradas CEST (esperado >= 500)"
+        if not any(e.code == "03.021.03" for e in parsed.entries):
+            errors["KNOWN_SAMPLE_MISSING"] = "CEST conhecido 03.021.03 (cervejas) não encontrado"
+        return parsed, errors
+
+    elif name == "nfe_domains":
+        from central.app.datasets.nfe_moc_tables import parse_moc_tables
+        parsed = parse_moc_tables(raw_bytes)
+        domains = {e.domain for e in parsed.entries}
+        expected = {"ORIGEM_MERCADORIA", "CST_ICMS", "CSOSN", "CST_PIS", "CST_COFINS", "CST_IPI", "UNIDADE_COMERCIAL"}
+        missing = expected - domains
+        if missing:
+            errors["DOMAINS_MISSING"] = f"Domínios ausentes no MOC: {sorted(missing)}"
+        if len(parsed.entries) < 80:
+            errors["MINIMUM_ENTRIES"] = f"Apenas {len(parsed.entries)} códigos de domínio (esperado >= 80)"
+        return parsed, errors
+
+    elif name == "cfop":
+        from central.app.datasets.bootstrap_v1_extra import parse_cfop
+        parsed = parse_cfop(raw_bytes)
+        if len(parsed.entries) < 200:
+            errors["MINIMUM_ENTRIES"] = f"Apenas {len(parsed.entries)} CFOPs (esperado >= 200)"
+        return parsed, errors
+
+    raise ValueError(f"Fonte desconhecida: {name}")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Ingestão de datasets oficiais no Reference Data Registry")
+    ap.add_argument("source", choices=sorted(SOURCES), help="Nome do dataset oficial a ingerir")
+    ap.add_argument("--file", type=Path, default=None, help="Caminho local para o arquivo oficial")
+    ap.add_argument("--dry-run", action="store_true", help="Apenas valida e simula sem persistir no Postgres")
+    ap.add_argument("--force", action="store_true", help="Ignora cache local e força novo download")
+    a = ap.parse_args()
+
+    src = SOURCES[a.source]
+    path, origin_msg, fetch_errors = fetch_or_fallback(a.source, file_path=a.file, force=a.force)
+    print(f"STATUS_ORIGEM: {origin_msg}")
+
+    if fetch_errors:
+        report = {
+            "source": a.source,
+            "kind": src["kind"],
+            "provider": src["provider"],
+            "url": src["url"],
+            "status": "IMPORT_MANUAL",
+            "parse_errors": fetch_errors,
+        }
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return
+
+    raw_bytes = path.read_bytes()
+    sha256 = hashlib.sha256(raw_bytes).hexdigest()
+    size = len(raw_bytes)
+
+    try:
+        parsed, parse_errors = validate_and_parse(a.source, path, raw_bytes)
+        record_count = len(parsed.entries)
+        version_label = getattr(parsed, "version", None) or getattr(parsed, "parser_version", "v1")
+    except Exception as exc:
+        parsed = None
+        record_count = 0
+        version_label = "parse-failed"
+        parse_errors = {"PARSER_EXCEPTION": str(exc)}
+
+    rel_path = str(path.relative_to(ROOT)) if path.is_relative_to(ROOT) else str(path)
+    report = {
+        "source": a.source,
+        "kind": src["kind"],
+        "provider": src["provider"],
+        "url": src["url"],
+        "sha256": sha256,
+        "file_size_bytes": size,
+        "record_count": record_count,
+        "version_label": version_label,
+        "act": src["act"],
+        "licence_terms": src["licence"],
+        "raw_file_path": rel_path,
+        "parse_errors": parse_errors,
+        "status": "DRAFT",
+    }
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+
+    if a.dry_run:
+        print("DRY_RUN: Validação concluída. Nenhum dado foi persistido no banco.")
+        return
+
+    # Persistência no Postgres como DRAFT
+    from central.app.reference_registry import register_draft
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import Session
+
+    db_url = os.environ.get("DATABASE_URL", "postgresql://postgres:postgres@localhost:5432/central")
+    try:
+        engine = create_engine(db_url)
+        with Session(engine) as session:
+            dataset = register_draft(
+                session,
+                kind=src["kind"],
+                provider=src["provider"],
+                source_url=src["url"],
+                sha256=sha256,
+                version_label=version_label,
+                act=src["act"],
+                record_count=record_count,
+                parse_errors=parse_errors,
+                licence_terms=src["licence"],
+                raw_file_path=rel_path,
+                file_size_bytes=size,
+                submitted_by="cli_ingestion",
+            )
+            print(f"REGISTRADO_COM_SUCESSO: dataset_id={dataset.id} status={dataset.status}")
+    except Exception as db_err:
+        print(f"AVISO_POSTGRES: Não foi possível conectar ao banco ({db_err}). Validação CLI concluída com sucesso.")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/inspect_erp_table.py

@@ -0,0 +1,22 @@
+"""Read-only: per-column stats for a table. usage: inspect_erp_table.py TABLE [regex-of-cols]"""
+import os, re, sys
+from pathlib import Path
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+from gti_fiscal_agent.firebird_reader import _connect
+for l in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+    if "=" in l and not l.startswith("#"):
+        k, _, v = l.partition("="); os.environ.setdefault(k.strip(), v.strip())
+t = sys.argv[1]; rx = re.compile(sys.argv[2], re.I) if len(sys.argv) > 2 else None
+conn = _connect(os.environ); cur = conn.cursor()
+cur.execute("select trim(rf.RDB$FIELD_NAME), f.RDB$FIELD_TYPE, coalesce(f.RDB$CHARACTER_LENGTH,f.RDB$FIELD_LENGTH) from RDB$RELATION_FIELDS rf join RDB$FIELDS f on f.RDB$FIELD_NAME=rf.RDB$FIELD_SOURCE where rf.RDB$RELATION_NAME=? order by rf.RDB$FIELD_POSITION", (t,))
+for name, ty, ln in cur.fetchall():
+    if rx and not rx.search(name): continue
+    if ty in (261,):  # blob
+        print(f"{name} BLOB"); continue
+    cur.execute(f'select "{name}", count(*) from "{t}" group by "{name}" order by 2 desc rows 1 to 400')
+    rows = cur.fetchall()
+    nn = sum(c for v, c in rows if v is not None)
+    top = [(str(v).strip()[:24] if v is not None else None, c) for v, c in rows[:5]]
+    print(f"{name} t{ty}/{ln} nn={nn} distinct{'>=' if len(rows)>=400 else '='}{len(rows)} {top}")
+conn.close()

fiscal/scripts/inventory_final_incomplete.py

@@ -0,0 +1,116 @@
+"""Inventory the exact final incomplete products using read-only Firebird queries."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from central.app.fiscal_completeness import evaluate_product, load_requiredness_matrix  # noqa: E402
+from central.app.ai.fingerprint import product_fingerprint, validate_gtin  # noqa: E402
+
+
+def load_env():
+    path = ROOT / ".env"
+    if path.exists():
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if "=" in line and not line.lstrip().startswith("#"):
+                key, _, value = line.partition("=")
+                os.environ.setdefault(key.strip(), value.strip())
+
+
+def _context(cur):
+    cur.execute("SELECT UF, CRT FROM C000004")
+    rows = {(str(uf or '').strip().upper(), str(crt or '').strip()) for uf, crt in cur.fetchall()}
+    return next(iter(rows)) if len(rows) == 1 else (None, None)
+
+
+def _blocker(field: str, company_context: bool) -> str:
+    if not company_context:
+        return "MISSING_COMPANY_CONTEXT"
+    if field == "SITUACAO_TRIBUTARIA":
+        return "MISSING_ST_FACT"
+    return "OTHER_PROVEN_BLOCKER"
+
+
+def inventory_database(path: Path, matrix: dict) -> list[dict]:
+    import fdb
+
+    conn = fdb.connect(database=str(path), user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"), isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT TRIM(RDB$FIELD_NAME) FROM RDB$RELATION_FIELDS WHERE RDB$RELATION_NAME = 'C000025'")
+        available = {row[0] for row in cur.fetchall()}
+        selected = [field for field in matrix["fields"] if field in available]
+        identity_fields = [field for field in ("CODIGO", "PRODUTO", "GTIN", "CODBARRA", "UNIDADE", "CLASSIFICACAO_FISCAL", "NCM", "CODGRUPO", "CODSUBGRUPO") if field in available]
+        cur.execute(f"SELECT {','.join(identity_fields + selected)} FROM C000025")
+        names = identity_fields + selected
+        product_rows = cur.fetchall()
+        uf, crt = _context(cur)
+        company_context = uf is not None and crt in {"1", "2", "3"}
+        result = []
+        for row in product_rows:
+            product = dict(zip(names, row))
+            context = {
+                "uf": uf, "crt": crt, "regime": "SIMPLES" if crt == "1" else "NORMAL" if crt in {"2", "3"} else None,
+                "operation": "SALE", "contribuinte_ipi": "N", "has_numeric_tipi": False, "has_supported_ex": False,
+                "product_matches_ex": False, "has_official_cest": bool(str(product.get("CEST") or "").strip()),
+                "st_subject": str(product.get("SITUACAO_TRIBUTARIA") or "").strip() == "S", "erp_consumes_entry_fields": False,
+                "icms_taxed": str(product.get("SITUACAO_TRIBUTARIA") or "").strip() == "T", "origin_proven": False,
+                "erp_consumes_ipi_cst": False, "piscofins_profile_proven": False, "piscofins_rate_applies": False,
+            }
+            evaluation = evaluate_product(product, context, matrix)
+            missing = []
+            for field, field_result in evaluation["fields"].items():
+                if field_result["status"] != "REQUIRED_MISSING":
+                    continue
+                missing.append({
+                    "FIELD": field,
+                    "WHY_REQUIRED": matrix["fields"][field]["when"],
+                    "CURRENT_VALUE": product.get(field),
+                    "WHY_UNRESOLVED": "required value is absent or invalid and no deterministic source proved a replacement",
+                    "EVIDENCE_AVAILABLE": ["C000004 company context" if company_context else "company context unavailable", "C000025 product master", "read-only inbound evidence map"],
+                    "BLOCKER_CLASS": _blocker(field, company_context),
+                })
+            if missing:
+                result.append({
+                    "DATABASE": path.stem,
+                    "PRODUCT_CODE": str(product.get("CODIGO") or "").strip(),
+                    "DESCRIPTION": str(product.get("PRODUTO") or "").strip(),
+                    "GTIN": validate_gtin(product.get("GTIN") or product.get("CODBARRA")),
+                    "GTIN_RAW": product.get("GTIN") or product.get("CODBARRA"),
+                    "FINGERPRINT": product_fingerprint(product.get("PRODUTO"), None, product.get("UNIDADE")),
+                    "NCM_CURRENT": product.get("CLASSIFICACAO_FISCAL") or product.get("NCM"),
+                    "GROUP": product.get("CODGRUPO"),
+                    "SUBGROUP": product.get("CODSUBGRUPO"),
+                    "REQUIRED_MISSING": missing,
+                    "PRIORITY_CLASS": "HUMAN_FACT_REQUIRED" if not company_context else "RESOLVABLE_NOW_DETERMINISTICALLY_CANDIDATE",
+                })
+        return result
+    finally:
+        conn.close()
+
+
+def main():
+    load_env()
+    matrix = load_requiredness_matrix(ROOT / "docs/FISCAL_REQUIREDNESS_MATRIX_V1.json")
+    paths = [ROOT / "TESTESOFICIAIS.FDB"] + sorted((ROOT / "Banco").glob("*.FDB"))
+    products = []
+    for path in paths:
+        products.extend(inventory_database(path, matrix))
+    blockers = Counter(item["BLOCKER_CLASS"] for product in products for item in product["REQUIRED_MISSING"])
+    artifact = {
+        "artifact": "FINAL_INCOMPLETE_PRODUCTS_V1", "mode": "READ_ONLY", "total_incomplete_products": len(products),
+        "unique_product_keys": len({(p["DATABASE"], p["PRODUCT_CODE"]) for p in products}), "blockers_by_type": dict(sorted(blockers.items())),
+        "products": products, "firebird_writes": 0, "external_api_calls": 0,
+    }
+    (ROOT / "docs/FINAL_INCOMPLETE_PRODUCTS_V1.json").write_text(json.dumps(artifact, ensure_ascii=False, indent=2, default=str) + "\n", encoding="utf-8")
+    print(json.dumps({"artifact": artifact["artifact"], "total_incomplete_products": len(products), "blockers_by_type": artifact["blockers_by_type"]}))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/local_completion.py

@@ -0,0 +1,398 @@
+"""GTI Fiscal LOCAL COMPLETION V1 runner: snapshot -> dry-run -> guarded apply -> verify -> second pass -> reports/questions.
+
+    python scripts/local_completion.py <stage> [--db NAME ...]
+      stages: snapshot | dryrun | apply | verify | second | report | questions | all
+
+Databases are ONLY those in docs/LOCAL_WRITE_ALLOWLIST_V1.json (exact canonical paths). Writes go through
+scripts/firebird_write_executor.execute_guarded_product_update (path allowlist, schema/type/length guard, compare-before-write,
+one UPDATE per product, rowcount, independent re-read). Nothing is written by any stage except `apply` (and `second`, which must write 0).
+State lives in docs/runs/local_completion/ (git-ignored bulk files).
+"""
+import argparse
+import gzip
+import hashlib
+import importlib.util
+import json
+import os
+import pickle
+import subprocess
+import sys
+import tempfile
+from collections import Counter, defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+import fdb  # noqa: E402
+import run_fiscal_decision_v1 as base  # noqa: E402
+from central.app.field_contract import ALREADY, CHANGE, CONTRACT, CONTRACT_VERSION, CORRECTED, MANUAL, NA, WRITE_FIELDS, Context, resolve_product  # noqa: E402
+from gti_fiscal_agent import company_context as cc  # noqa: E402
+from gti_fiscal_agent.coverage import build_refs  # noqa: E402
+from gti_fiscal_agent.firebird_reader import read_evidence  # noqa: E402
+
+STATE = ROOT / "docs" / "runs" / "local_completion"
+HUB = "http://localhost:8000"
+# Per-database company configuration (operator decisions recorded in docs/AGENT_COMPANY_CONTEXT_RULES_V1.md): the three databases with a CRT conflict use the
+# emission authority EMISSOR; the company is always the C000004 row 000001 (the one whose CNPJ equals the EMISSOR CNPJ).
+COMPANY_CFG = {"CONSTRUCAO": {"company_code": "000001"}, "MMMODAS": {"company_code": "000001", "crt_source": "EMISSOR"}, "RINCAO": {"company_code": "000001", "crt_source": "EMISSOR"},
+               "UNIAO": {"company_code": "000001", "crt_source": "EMISSOR"}, "TESTESOFICIAIS": {}}
+BASE_COLS = ["CODIGO", "PRODUTO", "CODGRUPO", "TIPO", "PROD_COZINHA", "PRODUTO_SERVICO"]
+s_ = lambda v: None if v is None else str(v).strip()  # noqa: E731
+
+
+def load_executor():
+    spec = importlib.util.spec_from_file_location("firebird_write_executor", ROOT / "scripts" / "firebird_write_executor.py")
+    mod = importlib.util.module_from_spec(spec); sys.modules[spec.name] = mod; spec.loader.exec_module(mod)
+    return mod
+
+
+def allowlist():
+    doc = json.loads((ROOT / "docs" / "LOCAL_WRITE_ALLOWLIST_V1.json").read_text(encoding="utf-8"))
+    return {d["name"]: d["path"] for d in doc["databases"]}
+
+
+def connect(path, rw=False):
+    kw = dict(database=path, user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"))
+    if not rw:
+        kw["isolation_level"] = fdb.ISOLATION_LEVEL_READ_COMMITED_RO
+    return fdb.connect(**kw)
+
+
+def env_for(path):
+    return {"FIREBIRD_DATABASE_PATH": path, "FB_USER": os.environ["FB_USER"], "FB_PASSWORD": os.environ["FB_PASSWORD"], "FIREBIRD_CLIENT_LIBRARY": os.environ.get("FIREBIRD_CLIENT_LIBRARY")}
+
+
+# ------------------------------------------------------------------------------------------------------------------ snapshot
+def snapshot(name, path):
+    conn = connect(path); cur = conn.cursor()
+    cur.execute("SELECT TRIM(rf.RDB$FIELD_NAME), f.RDB$FIELD_TYPE FROM RDB$RELATION_FIELDS rf JOIN RDB$FIELDS f ON f.RDB$FIELD_NAME = rf.RDB$FIELD_SOURCE WHERE rf.RDB$RELATION_NAME = 'C000025' ORDER BY rf.RDB$FIELD_POSITION")
+    cols = [c for c, t in cur.fetchall() if t != 261]  # blobs (images) excluded
+    cur.execute(f"SELECT {', '.join(cols)} FROM C000025 ORDER BY CODIGO")
+    rows = {s_(r[cols.index("CODIGO")]): tuple(r) for r in cur.fetchall()}
+    side = {}
+    for t in ("C000004", "EMISSOR"):
+        try:
+            cur.execute(f"SELECT * FROM {t}")
+            names = [d[0] for d in cur.description]
+            data = [tuple(v.read() if hasattr(v, "read") else v for v in r) for r in cur.fetchall()]
+            side[t] = {"columns": names, "rows": data, "sha256": hashlib.sha256(repr(data).encode("utf-8", "replace")).hexdigest()}
+        except Exception as e:  # noqa: BLE001
+            side[t] = {"error": type(e).__name__}
+    company = cc.resolve(cc.collect_evidence(cur), cc.config_from_env({k.upper(): v for k, v in _cfg_env(name).items()}))
+    conn.close()
+    snap = {"name": name, "path": path, "taken": datetime.now(timezone.utc).isoformat(timespec="seconds"), "columns": cols, "rows": rows, "side_tables": side,
+            "product_count": len(rows), "products_logical_sha256": hashlib.sha256(repr(sorted(rows.items())).encode("utf-8", "replace")).hexdigest(),
+            "company": {k: company.get(k) for k in ("status", "classification", "company_code", "company_cnpj", "company_uf", "company_crt", "source_of_truth", "confidence", "warnings", "reasons")}}
+    STATE.mkdir(parents=True, exist_ok=True)
+    with gzip.open(STATE / f"{name}_before.pkl.gz", "wb") as f:
+        pickle.dump(snap, f)
+    return snap
+
+
+def _cfg_env(name):
+    cfg = COMPANY_CFG.get(name, {})
+    out = {}
+    if cfg.get("company_code"): out["COMPANY_CODE"] = cfg["company_code"]
+    if cfg.get("crt_source"): out["COMPANY_CRT_SOURCE"] = cfg["crt_source"]
+    return out
+
+
+def load_snapshot(name):
+    with gzip.open(STATE / f"{name}_before.pkl.gz", "rb") as f:
+        return pickle.load(f)
+
+
+# ------------------------------------------------------------------------------------------------------------------ analysis
+def classify_pairs(pairs):
+    pairs = sorted(set(pairs))
+    with tempfile.TemporaryDirectory() as tmp:
+        fin, fout = Path(tmp) / "in.json", Path(tmp) / "out.json"
+        fin.write_text(json.dumps(pairs, ensure_ascii=False), encoding="utf-8")
+        subprocess.run(["docker", "cp", str(ROOT / "scripts" / "bulk_classify_in_container.py"), "projeto-fiscal-hub-1:/tmp/bulk.py"], check=True)
+        subprocess.run(["docker", "cp", str(fin), "projeto-fiscal-hub-1:/tmp/in.json"], check=True)
+        subprocess.run(["docker", "exec", "projeto-fiscal-hub-1", "sh", "-c", "cd /app && python /tmp/bulk.py /tmp/in.json /tmp/out.json"], check=True, capture_output=True)
+        subprocess.run(["docker", "cp", "projeto-fiscal-hub-1:/tmp/out.json", str(fout)], check=True)
+        return dict(zip(pairs, json.loads(fout.read_text(encoding="utf-8"))))
+
+
+def hub_get(path, token):
+    return base.http(HUB + path, token)
+
+
+def analyze(name, path, token, snap=None, extra_context=None):
+    """Read the database (read-only) and resolve every product/field. Returns the full analysis."""
+    conn = connect(path); cur = conn.cursor()
+    cur.execute("SELECT TRIM(RDB$FIELD_NAME) FROM RDB$RELATION_FIELDS WHERE RDB$RELATION_NAME = 'C000025'")
+    have = {r[0] for r in cur.fetchall()}
+    cols = [c for c in BASE_COLS + WRITE_FIELDS if c in have]
+    cur.execute(f"SELECT {', '.join(cols)} FROM C000025 ORDER BY CODIGO")
+    products = []
+    for r in cur.fetchall():
+        p = {c: None for c in BASE_COLS + WRITE_FIELDS}
+        p.update(zip(cols, r))
+        for k in p:
+            if isinstance(p[k], str):
+                p[k] = p[k].strip()
+        products.append(p)
+    company = cc.resolve(cc.collect_evidence(cur), cc.config_from_env(_cfg_env(name)))
+    ev_rows = cc.collect_evidence(cur)
+    sel = next((c for c in ev_rows["c000004"] if c["code"] == company["company_code"]), {})
+    groups = {}
+    if "C000017" in {r[0] for r in _tables(cur)}:
+        cur.execute("SELECT TRIM(CODIGO), TRIM(GRUPO) FROM C000017")
+        groups = dict(cur.fetchall())
+    contrib = None
+    if "CONTRIBUINTE_IPI" in _cols(cur, "C000004"):
+        cur.execute("SELECT CODIGO, CONTRIBUINTE_IPI FROM C000004")
+        contrib = {s_(a): s_(b) for a, b in cur.fetchall()}.get(company["company_code"])
+    conn.close()
+    if company["status"] != "PASS":
+        raise RuntimeError(f"{name}: company context {company['classification']}: {company['reasons']}")
+    comp = {"uf": company["company_uf"], "crt": company["company_crt"], "contribuinte_ipi": contrib, "company_code": company["company_code"], "company_key": company["company_cnpj_fingerprint"]}
+    # ERP-emission evidence: the SGV NFC-e history shows whether the PIS/COFINS cadastral fields are consumed at emission (issued CST_PIS_COFINS non-blank share)
+    try:
+        _c = connect(path); _cur = _c.cursor()
+        _cur.execute("SELECT COUNT(*), COUNT(NULLIF(TRIM(CST_PIS_COFINS), '')) FROM NFCE_ITENS")
+        tot, nonblank = _cur.fetchone(); _c.close()
+        comp["pis_cofins_emission_items"] = tot; comp["pis_cofins_emission_nonblank"] = nonblank
+        comp["pis_cofins_unused_by_emission"] = bool(tot >= 1000 and nonblank / tot < 0.001)
+    except Exception as exc:  # noqa: BLE001
+        comp["pis_cofins_unused_by_emission"] = False; comp["pis_cofins_evidence_error"] = str(exc)[:120]
+    evidence = read_evidence(env_for(path), company["company_code"])
+    refs = build_refs(lambda p: hub_get(p, token), products, comp["uf"])
+    entries = list(extra_context or [])
+    try:
+        entries += hub_get(f"/v1/context?company_key={comp['company_key']}", token)["entries"]
+    except Exception:  # noqa: BLE001
+        pass
+    ctx = Context(entries)
+    manual = {}
+    for p in products:
+        v, _ = ctx.get("ncm", s_(p["CODIGO"]))
+        if v:
+            manual[s_(p["CODIGO"])] = v
+    pairs = [(s_(p["CLASSIFICACAO_FISCAL"]) or "", s_(p["PRODUTO"]) or "") for p in products] + [(v, s_(p["PRODUTO"]) or "") for p in products for v in [manual.get(s_(p["CODIGO"]))] if v]
+    dec = classify_pairs(pairs)
+    results = {}
+    dup_codes = {c: n for c, n in Counter(s_(p["CODIGO"]) for p in products).items() if n > 1}
+    seen = Counter()
+    for p in products:
+        code = s_(p["CODIGO"]); desc = s_(p["PRODUTO"]) or ""
+        seen[code] += 1
+        rk = code if seen[code] == 1 else f"{code}#{seen[code]}"
+        p["_rk"] = rk
+        m = manual.get(code)
+        md = dec[(m, desc)] if m else None
+        valid_manual = bool(md and md.get("status") == "EXACT_NCM")
+        d = md if valid_manual else dec[(s_(p["CLASSIFICACAO_FISCAL"]) or "", desc)]
+        results[rk] = resolve_product(p, d, comp, refs, evidence, ctx, manual_ncm=(m, valid_manual) if m else None)
+        if dup_codes.get(code, 1) > 1:  # data-integrity defect (PK violation in the copy): every physical row that shares the code is blocked, all 23 cells stay accounted
+            for f in WRITE_FIELDS:
+                r = results[rk][f]
+                r.update(state=MANUAL, reason="DUPLICATE_KEY_BLOCKED", input_key="duplicate_code", input_scope="PRODUCT", write_eligible=False, proposed=None)
+        results[rk]["_ds"] = {k: (v or "")[:8] for k, v in (d.get("dataset_versions") or {}).items() if k in ("ncm", "tipi_ipi", "cest", "ba_st_mva", "cfop", "nfe_moc_tables")}
+    return {"name": name, "path": path, "products": products, "company": comp, "company_result": company, "results": results, "groups": groups, "context_entries": len(entries), "engine": {"contract": CONTRACT_VERSION}}
+
+
+def _tables(cur):
+    cur.execute("SELECT TRIM(RDB$RELATION_NAME) FROM RDB$RELATIONS WHERE COALESCE(RDB$SYSTEM_FLAG,0)=0")
+    return cur.fetchall()
+
+
+def _cols(cur, table):
+    cur.execute("SELECT TRIM(RDB$FIELD_NAME) FROM RDB$RELATION_FIELDS WHERE RDB$RELATION_NAME = ?", (table,))
+    return {r[0] for r in cur.fetchall()}
+
+
+def summarize(an):
+    per = {f: Counter() for f in WRITE_FIELDS}
+    reasons = {f: Counter() for f in WRITE_FIELDS}
+    manual_keys = Counter()
+    for code, res in an["results"].items():
+        for f in WRITE_FIELDS:
+            r = res[f]
+            per[f][r["state"]] += 1
+            reasons[f][(r["state"], r["reason"])] += 1
+            if r["state"] == MANUAL:
+                manual_keys[(f, r["input_key"])] += 1
+    roles = Counter(res["_facts"]["role"] for res in an["results"].values())
+    return {"name": an["name"], "total_products": len(an["products"]), "company": an["company"], "context_entries": an["context_entries"],
+            "fields": {f: dict(per[f]) for f in WRITE_FIELDS}, "reasons": {f: {f"{s}|{r}": n for (s, r), n in reasons[f].most_common(12)} for f in WRITE_FIELDS},
+            "manual_inputs": {f"{f}|{k}": n for (f, k), n in manual_keys.most_common()}, "roles": dict(roles),
+            "change_required_cells": sum(per[f][CHANGE] for f in WRITE_FIELDS), "write_eligible_cells": sum(1 for res in an["results"].values() for f in WRITE_FIELDS if res[f]["write_eligible"])}
+
+
+def write_ndjson(name, an, suffix):
+    with gzip.open(STATE / f"{name}_{suffix}.ndjson.gz", "wt", encoding="utf-8") as f:
+        for p in an["products"]:
+            code = s_(p["CODIGO"]); res = an["results"][p["_rk"]]
+            for fld in WRITE_FIELDS:
+                r = res[fld]
+                f.write(json.dumps({"db": an["name"], "codigo": code, "row_key": p["_rk"], "field": fld, "before": r["current"], "proposed": r["proposed"], "status": r["state"], "reason": r["reason"], "input_key": r["input_key"],
+                                    "provenance": f"{CONTRACT_VERSION}|" + ",".join(f"{k}:{v}" for k, v in res["_ds"].items()) + f"|role={res['_facts']['role']}", "write_eligible": r["write_eligible"]}, ensure_ascii=False, default=str) + "\n")
+
+
+# ------------------------------------------------------------------------------------------------------------------ apply / verify
+def apply(name, path, an, snap):
+    ex = load_executor()
+    ex.assert_local_completion_target(path)
+    run_id = hashlib.sha256(f"{name}|{snap['taken']}|{snap['products_logical_sha256']}".encode()).hexdigest()[:16]
+    now_company = cc.resolve(cc.collect_evidence(_ro_cursor(path)), cc.config_from_env(_cfg_env(name)))
+    if now_company["status"] != "PASS" or (now_company["company_uf"], now_company["company_crt"]) != (an["company"]["uf"], an["company"]["crt"]):
+        raise RuntimeError("company-context guard failed before writing")
+    cols = snap["columns"]
+    conn = connect(path, rw=True)
+    audit, failed, attempted, succeeded = [], [], 0, 0
+    try:
+        for p in an["products"]:
+            code = s_(p["CODIGO"]); res = an["results"][code]
+            changes = {}
+            for f in WRITE_FIELDS:
+                r = res[f]
+                if r["write_eligible"]:
+                    changes[f] = (snap["rows"][code][cols.index(f)], r["proposed"])
+            if not changes:
+                continue
+            attempted += len(changes)
+            try:
+                rec = ex.execute_guarded_product_update(conn, database_path=path, product_code=code, changes=changes, now=datetime.now(timezone.utc).isoformat(timespec="seconds"))
+                audit.append({"db": name, "run_id": run_id, **rec, "outcome": "SUCCEEDED"})
+                succeeded += len(changes)
+            except ex.WriteRefused as e:
+                failed.append({"db": name, "run_id": run_id, "product_code": code, "fields": list(changes), "error": str(e)[:200]})
+    finally:
+        conn.close()
+    with gzip.open(STATE / f"{name}_write_audit.ndjson.gz", "wt", encoding="utf-8") as f:
+        for a in audit + [{**x, "outcome": "FAILED"} for x in failed]:
+            f.write(json.dumps(a, ensure_ascii=False, default=str) + "\n")
+    return {"name": name, "cells_attempted": attempted, "cells_succeeded": succeeded, "cells_failed": sum(len(x["fields"]) for x in failed), "products_updated": len(audit), "failures": failed[:20]}
+
+
+def _ro_cursor(path):
+    return connect(path).cursor()
+
+
+def verify(name, path, an, snap):
+    conn = connect(path); cur = conn.cursor()
+    cols = snap["columns"]
+    cur.execute(f"SELECT {', '.join(cols)} FROM C000025 ORDER BY CODIGO")
+    after = {s_(r[cols.index("CODIGO")]): tuple(r) for r in cur.fetchall()}
+    conn.close()
+    norm = lambda v: None if v is None else (round(float(v), 6) if isinstance(v, (int, float)) or v.__class__.__name__ == "Decimal" else str(v).strip())  # noqa: E731
+    planned = verified = bad_planned = unplanned_changes = 0
+    problems = []
+    for p in an["products"]:
+        code = s_(p["CODIGO"]); before = snap["rows"][code]; aft = after.get(code)
+        if aft is None:
+            problems.append((code, "MISSING_AFTER")); continue
+        exp = {f: an["results"][code][f]["proposed"] for f in WRITE_FIELDS if an["results"][code][f]["write_eligible"]}
+        for i, c in enumerate(cols):
+            if c in exp:
+                planned += 1
+                if norm(aft[i]) == norm(exp[c]):
+                    verified += 1
+                else:
+                    bad_planned += 1; problems.append((code, c, "AFTER!=PROPOSED", aft[i], exp[c]))
+            elif norm(aft[i]) != norm(before[i]):
+                unplanned_changes += 1; problems.append((code, c, "UNPLANNED_CHANGE", before[i], aft[i]))
+    return {"name": name, "products_after": len(after), "products_before": len(snap["rows"]), "planned_cells": planned, "post_write_verified": verified, "planned_mismatch": bad_planned,
+            "unplanned_changes": unplanned_changes, "problems": problems[:20]}
+
+
+# ------------------------------------------------------------------------------------------------------------------ questions
+def questions(analyses):
+    groups = defaultdict(lambda: {"products": [], "fields": Counter(), "choices": None, "examples": []})
+    for an in analyses:
+        by_code = {s_(p["CODIGO"]): p for p in an["products"]}
+        for code, res in an["results"].items():
+            p = by_code[code]
+            for f in WRITE_FIELDS:
+                r = res[f]
+                if r["state"] != MANUAL:
+                    continue
+                key, scope = r["input_key"], r["input_scope"]
+                if key in ("ncm",):
+                    gk = (an["name"], key, "PRODUCT", code, "")
+                elif key in ("cest", "ex_tipi"):
+                    ncm = "".join(c for c in (p["CLASSIFICACAO_FISCAL"] or "") if c.isdigit())
+                    gk = (an["name"], key, "NCM", ncm, "")
+                elif scope == "COMPANY" or key in ("entry_scope", "rounding", "icms_rate", "credit_rate", "pis_cofins_profile", "crt"):
+                    gk = (an["name"], key, "COMPANY", "", "")
+                else:
+                    grp = s_(p["CODGRUPO"]) or "(sem grupo)"
+                    gk = (an["name"], key, "GROUP", grp, an["groups"].get(grp, ""))
+                g = groups[gk]
+                g["products"].append(code); g["fields"][f] += 1
+                if r.get("choices") and g["choices"] is None:
+                    g["choices"] = r["choices"]
+                if len(g["examples"]) < 3:
+                    g["examples"].append(f"{code} {s_(p['PRODUTO'])[:40]}")
+    from central.app.context_keys import ENUMS
+    out = []
+    for (db, key, scope, skey, gname), g in sorted(groups.items()):
+        allowed = sorted(ENUMS[key]) if key in ENUMS else ("JSON {pis_in_cst,pis_out_cst,pis_rate,cofins_in_cst,cofins_out_cst,cofins_rate}" if key == "pis_cofins_profile" else "free text (see key)")
+        out.append({"database": db, "company_key": next(a["company"]["company_key"] for a in analyses if a["name"] == db), "key": key, "scope": scope, "scope_key": skey, "group_name": gname,
+                    "products_affected": len(set(g["products"])), "fields_affected": dict(g["fields"]), "allowed_values": allowed, "candidate_choices": g["choices"], "examples": g["examples"], "answer": ""})
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("stage"); ap.add_argument("--db", nargs="*")
+    a = ap.parse_args()
+    base.load_dotenv(ROOT / ".env")
+    token = os.environ["AGENT_DEV_TOKEN"]
+    allow = allowlist()
+    names = a.db or list(allow)
+    for n in names:
+        if n not in allow:
+            raise SystemExit(f"{n} is not in the exact write allowlist")
+    STATE.mkdir(parents=True, exist_ok=True)
+    analyses = []
+    for name in names:
+        path = allow[name]
+        print(f"== {name} :: {a.stage}", flush=True)
+        if a.stage in ("snapshot", "all"):
+            snap = snapshot(name, path)
+            print(f"   snapshot: {snap['product_count']} products, company {snap['company'].get('classification')}", flush=True)
+        if a.stage in ("dryrun", "apply", "verify", "second", "report", "questions", "all"):
+            snap = load_snapshot(name)
+        if a.stage in ("dryrun", "all", "apply"):
+            an = analyze(name, path, token, snap)
+            (STATE / f"{name}_dryrun_summary.json").write_text(json.dumps(summarize(an), ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+            write_ndjson(name, an, "dryrun")
+            print("   dry-run:", json.dumps({k: summarize(an)[k] for k in ("total_products", "change_required_cells", "write_eligible_cells")}), flush=True)
+            if a.stage in ("apply", "all"):
+                res = apply(name, path, an, snap)
+                (STATE / f"{name}_apply_summary.json").write_text(json.dumps(res, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+                print("   apply:", json.dumps({k: res[k] for k in ("cells_attempted", "cells_succeeded", "cells_failed", "products_updated")}), flush=True)
+                v = verify(name, path, an, snap)
+                (STATE / f"{name}_verify_summary.json").write_text(json.dumps(v, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+                print("   verify:", json.dumps({k: v[k] for k in ("planned_cells", "post_write_verified", "planned_mismatch", "unplanned_changes")}), flush=True)
+        if a.stage in ("second", "all"):
+            an2 = analyze(name, path, token, snap)
+            s2 = summarize(an2)
+            second = {"name": name, "SECOND_PASS_CHANGE_REQUIRED": s2["change_required_cells"], "SECOND_PASS_WRITES": 0, "fields": s2["fields"]}
+            if s2["write_eligible_cells"]:
+                second["SECOND_PASS_WRITES"] = apply(name, path, an2, snap)["cells_succeeded"]
+            (STATE / f"{name}_second_pass.json").write_text(json.dumps(second, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+            write_ndjson(name, an2, "second")
+            print("   second pass:", second["SECOND_PASS_CHANGE_REQUIRED"], second["SECOND_PASS_WRITES"], flush=True)
+        if a.stage in ("questions",):
+            analyses.append(analyze(name, path, token, snap))
+    if a.stage == "questions":
+        q = questions(analyses)
+        (ROOT / "docs" / "LOCAL_FISCAL_CONTEXT_QUESTIONS_V1.json").write_text(json.dumps({"artifact": "LOCAL_FISCAL_CONTEXT_QUESTIONS_V1", "total_questions": len(q), "questions": q}, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+        import csv
+        with open(ROOT / "docs" / "LOCAL_FISCAL_CONTEXT_QUESTIONS_V1.csv", "w", newline="", encoding="utf-8-sig") as f:
+            w = csv.writer(f)
+            w.writerow(["database", "company_key", "scope", "scope_key", "key", "group_name", "products_affected", "fields_affected", "allowed_values", "examples", "value", "reason"])
+            for x in q:
+                w.writerow([x["database"], x["company_key"], x["scope"], x["scope_key"], x["key"], x["group_name"], x["products_affected"], json.dumps(x["fields_affected"], ensure_ascii=False),
+                            x["allowed_values"] if isinstance(x["allowed_values"], str) else "|".join(x["allowed_values"]), " ; ".join(x["examples"]), "", ""])
+        print("questions:", len(q))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/local_completion_report.py

@@ -0,0 +1,69 @@
+"""Compose the LOCAL COMPLETION V1 artifacts from docs/runs/local_completion/* (no database access):
+docs/LOCAL_FULL_FISCAL_DRY_RUN_V1.json, docs/LOCAL_FULL_FISCAL_WRITE_AUDIT_V1.json, docs/LOCAL_DATABASE_VALIDATION_REPORT_V1.md, docs/local_completion_totals.json
+"""
+import gzip
+import json
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from central.app.field_contract import WRITE_FIELDS  # noqa: E402
+
+ST = ROOT / "docs" / "runs" / "local_completion"
+NAMES = [d["name"] for d in json.loads((ROOT / "docs" / "LOCAL_WRITE_ALLOWLIST_V1.json").read_text(encoding="utf-8"))["databases"]]
+load = lambda n, suffix: json.loads((ST / f"{n}_{suffix}.json").read_text(encoding="utf-8")) if (ST / f"{n}_{suffix}.json").exists() else None  # noqa: E731
+
+dry, audit_doc, per_db = {}, {}, {}
+totals = Counter()
+report = ["# LOCAL_DATABASE_VALIDATION_REPORT_V1", "",
+          "Local completion mission over the five authorized disposable copies. States per (product, field): ALREADY_CORRECT (incl. `DECLARED_VALID_NOT_CONTRADICTED`), CORRECTED (written and independently re-read), NOT_APPLICABLE, MANUAL_INPUT_REQUIRED(<input>), FAILED (write refused/failed). No cell is left in a generic state.", ""]
+for n in NAMES:
+    d, ap, vf, sp = load(n, "dryrun_summary"), load(n, "apply_summary"), load(n, "verify_summary"), load(n, "second_pass")
+    if not d:
+        continue
+    failed_by_field = Counter()
+    ok_by_field = Counter()
+    p = ST / f"{n}_write_audit.ndjson.gz"
+    if p.exists():
+        with gzip.open(p, "rt", encoding="utf-8") as f:
+            for line in f:
+                a = json.loads(line)
+                if a.get("outcome") == "SUCCEEDED":
+                    for fld in a["fields"]:
+                        ok_by_field[fld] += 1
+                else:
+                    for fld in a.get("fields", []):
+                        failed_by_field[fld] += 1
+    rows = {}
+    for f in WRITE_FIELDS:
+        c = d["fields"][f]
+        corrected = ok_by_field.get(f, 0)
+        failed = failed_by_field.get(f, 0)
+        rows[f] = {"ALREADY_CORRECT": c.get("ALREADY_CORRECT", 0), "CORRECTED": corrected, "NOT_APPLICABLE": c.get("NOT_APPLICABLE", 0), "MANUAL_INPUT_REQUIRED": c.get("MANUAL_INPUT_REQUIRED", 0), "FAILED": failed,
+                   "CHANGE_REQUIRED_planned": c.get("CHANGE_REQUIRED", 0)}
+    per_db[n] = {"total_products": d["total_products"], "fields": rows, "company": d["company"], "manual_inputs": d["manual_inputs"], "roles": d["roles"], "apply": ap, "verify": vf, "second_pass": sp}
+    for f in WRITE_FIELDS:
+        for k in ("ALREADY_CORRECT", "CORRECTED", "NOT_APPLICABLE", "MANUAL_INPUT_REQUIRED", "FAILED", "CHANGE_REQUIRED_planned"):
+            totals[k] += rows[f][k]
+            totals[f"{f}:{k}"] += rows[f][k]
+    dry[n] = {"total_products": d["total_products"], "company": d["company"], "states_before_writes": d["fields"], "top_reasons": d["reasons"], "manual_inputs": d["manual_inputs"], "roles": d["roles"],
+              "detail_file": f"docs/runs/local_completion/{n}_dryrun.ndjson.gz (git-ignored; one JSON line per product/field: BEFORE, PROPOSED, STATUS, REASON, PROVENANCE, WRITE_ELIGIBLE)"}
+    audit_doc[n] = {"path": "exact allowlist path", "apply": ap, "verify": vf, "second_pass": {k: sp[k] for k in ("SECOND_PASS_CHANGE_REQUIRED", "SECOND_PASS_WRITES")} if sp else None,
+                    "cells_by_field": {f: {"attempted": rows[f]["CORRECTED"] + rows[f]["FAILED"], "succeeded": rows[f]["CORRECTED"], "failed": rows[f]["FAILED"]} for f in WRITE_FIELDS if rows[f]["CORRECTED"] + rows[f]["FAILED"]},
+                    "detail_file": f"docs/runs/local_completion/{n}_write_audit.ndjson.gz"}
+    report += [f"## {n}", f"Produtos: {d['total_products']}  |  empresa: UF {d['company']['uf']} / CRT {d['company']['crt']} (código {d['company']['company_code']})", ""]
+    if ap:
+        report.append(f"Escrita: {ap['cells_succeeded']} células corrigidas em {ap['products_updated']} produtos ({ap['cells_failed']} falharam); verificação: {vf['post_write_verified']}/{vf['planned_cells']} conferem, {vf['unplanned_changes']} mudanças não planejadas.  Segunda passagem: CHANGE_REQUIRED={sp['SECOND_PASS_CHANGE_REQUIRED']}, writes={sp['SECOND_PASS_WRITES']}." if sp else f"Escrita: {ap['cells_succeeded']} células corrigidas; verificação {vf['post_write_verified']}/{vf['planned_cells']}.")
+    report += ["", "| campo | ALREADY_CORRECT | CORRECTED | NOT_APPLICABLE | MANUAL_INPUT_REQUIRED | FAILED |", "|---|---|---|---|---|---|"]
+    for f in WRITE_FIELDS:
+        r = rows[f]
+        report.append(f"| {f} | {r['ALREADY_CORRECT']} | {r['CORRECTED']} | {r['NOT_APPLICABLE']} | {r['MANUAL_INPUT_REQUIRED']} | {r['FAILED']} |")
+    report += ["", f"Células fiscais corrigidas: **{sum(rows[f]['CORRECTED'] for f in WRITE_FIELDS)}**.  Entradas manuais pedidas (campo|chave): " + ", ".join(f"{k}={v}" for k, v in list(d["manual_inputs"].items())[:8]) + " ...", ""]
+
+(ROOT / "docs" / "LOCAL_FULL_FISCAL_DRY_RUN_V1.json").write_text(json.dumps({"artifact": "LOCAL_FULL_FISCAL_DRY_RUN_V1", "contract": "field-contract-v1", "databases": dry}, ensure_ascii=False, indent=1), encoding="utf-8")
+(ROOT / "docs" / "LOCAL_FULL_FISCAL_WRITE_AUDIT_V1.json").write_text(json.dumps({"artifact": "LOCAL_FULL_FISCAL_WRITE_AUDIT_V1", "databases": audit_doc}, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+(ROOT / "docs" / "LOCAL_DATABASE_VALIDATION_REPORT_V1.md").write_text("\n".join(report) + "\n", encoding="utf-8")
+(ROOT / "docs" / "runs" / "local_completion" / "totals.json").write_text(json.dumps({"totals": dict(totals), "per_db": per_db}, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+print(json.dumps({k: v for k, v in totals.items() if ":" not in k}))

fiscal/scripts/map_product_ui_fields.py

@@ -0,0 +1,185 @@
+"""Assisted single-session mapping of the SGV "Cadastro de Produto" fiscal screen (READ-ONLY tool).
+
+    python scripts/map_product_ui_fields.py --product <CODIGO>
+
+For each UI field the tool shows CURRENT and SUGGESTED_TEMP, waits for ENTER while the operator changes ONLY that
+field in the SGV and saves, re-reads the whole C000025 row, diffs it against the previous baseline and records
+which column(s) changed. The tool never writes to Firebird and never touches the GUI. State is persisted after every
+step (docs/SGV_PRODUCT_FISCAL_UI_DIFF_SESSION_V1.json) so the session can be resumed.
+
+Binding classes: DIRECT_BINDING (one non-technical column changed) | DERIVED/COUPLED_FIELD (several changed;
+ALL recorded, none chosen) | AUTOMATIC_METADATA (only timestamp-like technical columns) | AMBIGUOUS (nothing changed
+or several changed without the expected one).
+"""
+import argparse
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src")); sys.path.insert(0, str(ROOT / "scripts"))
+
+SESSION = ROOT / "docs" / "SGV_PRODUCT_FISCAL_UI_DIFF_SESSION_V1.json"
+# Columns the ERP rewrites by itself on every save. Only these are ignored, and they are still listed in the record.
+TECHNICAL = {"ULTIMA_ALTERACAO", "DATA_ALTERACAO", "DATA_ULTIMA_ALTERACAO", "USUARIO_ALTERACAO"}
+
+# ui_label, hypothesised column (never trusted), candidate temporary values (first one different from CURRENT wins)
+SEQUENCE = [
+    ("NCM", "CLASSIFICACAO_FISCAL", ["22030000", "19022000"]),
+    ("CFOP entrada", "CFOP_ENTRADA", ["1102", "1949"]),
+    ("CFOP saída", "CFOP", ["5405", "5102", "5949"]),
+    ("CST ICMS entrada", "CST_ENTRADA", ["040", "000", "060"]),
+    ("CST ICMS saída", "CST", ["041", "000", "060"]),
+    ("Alíquota ICMS", "ALIQUOTA", ["12", "18", "17"]),
+    ("CEST", "CEST", ["0601100", "1708400"]),
+    ("CSOSN", "CSOSN", ["103", "500", "102"]),
+    ("PIS entrada", "COD_ENTRADA_PIS", ["73", "98", "50"]),
+    ("PIS saída", "COD_SAIDA_PIS", ["04", "01", "49"]),
+    ("Alíquota PIS", "ALIQ_PIS", ["0,65", "1,65"]),
+    ("COFINS entrada", "COD_ENTRADA_COFINS", ["73", "98", "50"]),
+    ("COFINS saída", "COD_SAIDA_COFINS", ["04", "01", "49"]),
+    ("Alíquota COFINS", "ALIQ_COFINS", ["3", "7,6"]),
+    ("IPI", "IPI", ["5", "10", "15"]),
+    ("CST IPI", "CST_IPI", ["50", "00", "99"]),
+    ("EX TIPI", "EX_TIPI", ["1", "2"]),
+    ("Origem", "ORIGEM", ["1", "2", "0"]),
+    ("IAT", "IAT", ["T", "A"]),
+    ("Incidência PIS/COFINS", "INCIDENCIA_PISCOFINS", ["MONOFÁSICA", "SUBST.TRIBUTÁRIA", "NENHUMA"]),
+    ("IPPT", "IPPT", ["P", "T"]),
+]
+
+
+def _same(a, b):
+    if a is None or b is None:
+        return a is None and b is None
+    try:
+        return float(str(a).replace(",", ".")) == float(str(b).replace(",", "."))
+    except ValueError:
+        return str(a).strip().upper() == str(b).strip().upper()
+
+
+def suggest_temp(current, candidates):
+    """First candidate that differs from the current value (never the same value, never blank)."""
+    for c in candidates:
+        if not _same(current, c):
+            return c
+    return None
+
+
+def classify(changes, expected_column):
+    """changes: [{'FIELD','BEFORE','AFTER','technical'}]. Never picks a column when several changed."""
+    real = [c["FIELD"] for c in changes if not c["technical"]]
+    tech = [c["FIELD"] for c in changes if c["technical"]]
+    if not real:
+        return "AUTOMATIC_METADATA" if tech else "AMBIGUOUS", "no fiscal column changed" if not tech else "only technical timestamp columns changed"
+    if len(real) == 1:
+        return "DIRECT_BINDING", "exactly one column changed" + ("" if real[0] == expected_column else f" (differs from hypothesis {expected_column})")
+    if expected_column in real:
+        return "DERIVED/COUPLED_FIELD", f"{len(real)} columns changed together; none selected"
+    return "AMBIGUOUS", f"{len(real)} columns changed and none is the hypothesis {expected_column}"
+
+
+def compute_diff(before, after):
+    return [{"FIELD": f, "BEFORE": before.get(f), "AFTER": after.get(f), "technical": f in TECHNICAL}
+            for f in sorted(set(before) | set(after)) if before.get(f) != after.get(f)]
+
+
+def new_session(product):
+    return {"artifact": "SGV_PRODUCT_FISCAL_UI_DIFF_SESSION_V1", "database": "TESTESOFICIAIS.FDB", "product": product, "started": datetime.now().isoformat(timespec="seconds"),
+            "initial_snapshot": None, "baseline": None, "results": [], "firebird_writes": 0}
+
+
+def save(session):
+    SESSION.write_text(json.dumps(session, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+
+
+def load_env():
+    for line in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+        if "=" in line and not line.startswith("#"):
+            k, _, v = line.partition("=")
+            os.environ.setdefault(k.strip(), v.strip())
+
+
+def run_step(session, ui_label, column, candidates, read_row, ask):
+    baseline = session["baseline"]
+    current = baseline.get(column) if column else None
+    temp = suggest_temp(current, candidates) if candidates else None
+    print(f"\nUI_FIELD={ui_label}\nCURRENT={current}\nSUGGESTED_TEMP={temp}\nHYPOTHESIS_COLUMN={column} (not trusted)")
+    answer = ask("Change ONLY this field in the SGV and save, then press ENTER  [s=skip (not on screen), q=quit]: ").strip().lower()
+    if answer == "q":
+        return "quit"
+    if answer == "s":
+        session["results"].append({"ui_label": ui_label, "hypothesis_column": column, "status": "NOT_ON_SCREEN", "at": datetime.now().isoformat(timespec="seconds")})
+        save(session)
+        return "skipped"
+    after = read_row()
+    changes = compute_diff(baseline, after)
+    binding, why = classify(changes, column)
+    rec = {"ui_label": ui_label, "hypothesis_column": column, "current": current, "suggested_temp": temp, "status": "TESTED", "binding_type": binding, "reason": why,
+           "db_fields_changed": [c["FIELD"] for c in changes if not c["technical"]], "technical_fields_changed": [c["FIELD"] for c in changes if c["technical"]],
+           "changes": changes, "at": datetime.now().isoformat(timespec="seconds")}
+    session["results"].append(rec)
+    session["baseline"] = after  # new state is the baseline for the next field
+    save(session)
+    print(f"UI_FIELD={ui_label}\nDB_FIELDS_CHANGED={rec['db_fields_changed']}\nBEFORE={ {c['FIELD']: c['BEFORE'] for c in changes} }\nAFTER={ {c['FIELD']: c['AFTER'] for c in changes} }\nBINDING={binding} ({why})")
+    return "tested"
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--product", required=True)
+    ap.add_argument("--restart", action="store_true", help="discard a previous session file for this product")
+    a = ap.parse_args(argv)
+    load_env()
+    from sgv_product_snapshot import read_row  # read-only single-row reader (read-only isolation)
+    from gti_fiscal_agent.firebird_reader import parse_company_context, _connect
+    path = os.environ.get("FIREBIRD_DATABASE_PATH", "")
+    if Path(path).name.upper() != "TESTESOFICIAIS.FDB":
+        raise SystemExit("this experiment is only for the disposable TESTESOFICIAIS.FDB (FIREBIRD_DATABASE_PATH)")
+    reader = lambda: read_row(os.environ, a.product)  # noqa: E731
+
+    if SESSION.exists() and not a.restart and json.loads(SESSION.read_text(encoding="utf-8")).get("product") == a.product:
+        session = json.loads(SESSION.read_text(encoding="utf-8"))
+        print(f"Resuming session ({len(session['results'])} results already recorded).")
+        session["baseline"] = reader()  # honour any manual change since the last step
+    else:
+        session = new_session(a.product)
+        session["initial_snapshot"] = session["baseline"] = reader()
+        save(session)
+    conn = _connect(os.environ)
+    try:
+        cur = conn.cursor(); cur.execute("SELECT UF, CRT FROM C000004")
+        session["company_context_read_from_db"] = parse_company_context(cur.fetchall())
+    finally:
+        conn.close()
+    done = {r["ui_label"] for r in session["results"]}
+    for ui_label, column, candidates in SEQUENCE:
+        if ui_label in done:
+            continue
+        if run_step(session, ui_label, column, candidates, reader, input) == "quit":
+            break
+    else:
+        while True:
+            extra = input("\nAny OTHER fiscal field visible on the screen? Type its label (or ENTER to finish): ").strip()
+            if not extra:
+                break
+            if run_step(session, extra, None, [], reader, input) == "quit":
+                break
+    session["finished"] = datetime.now().isoformat(timespec="seconds")
+    save(session)
+    changed = {}
+    for r in session["results"]:
+        for c in r.get("changes", []):
+            if not c["technical"]:
+                changed.setdefault(c["FIELD"], session["initial_snapshot"].get(c["FIELD"]))
+    print("\nSession saved:", SESSION)
+    if changed:
+        print("RESTORE_ORIGINAL_VALUES (set these back in the SGV):")
+        for f, v in changed.items():
+            print(f"  {f} = {v}")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/measure_scale_agent.py

@@ -0,0 +1,50 @@
+"""READ-ONLY phase timing of the Agent pipeline on a real database (default MMMODAS ~21k products) against the local dev Hub. Reports wall time per phase and peak RSS.
+    python scripts/measure_scale_agent.py [--db MMMODAS]"""
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path[:0] = [str(ROOT), str(ROOT / "scripts"), str(ROOT / "agent" / "src")]
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import local_completion as lc  # noqa: E402
+from central.app.operational_state import classify_product_state, summarize_operational_states  # noqa: E402
+from gti_fiscal_agent import firebird_reader, unified_fiscal  # noqa: E402
+from gti_fiscal_agent.client import HubClient  # noqa: E402
+from gti_fiscal_agent.runner import to_hub_product  # noqa: E402
+
+
+def rss_mb():
+    try:
+        import psutil
+        return round(psutil.Process().memory_info().rss / 1e6, 1)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def main():
+    ap = argparse.ArgumentParser(); ap.add_argument("--db", default="MMMODAS"); a = ap.parse_args()
+    path = lc.allowlist()[a.db]; env = lc.env_for(path)
+    out = {"database": a.db, "phases_seconds": {}}
+    t = time.time(); products = firebird_reader.read_products(env); out["phases_seconds"]["firebird_read"] = round(time.time() - t, 2); out["products"] = len(products)
+    t = time.time(); decisions = HubClient(os.environ.get("HUB_URL", lc.HUB), os.environ["AGENT_DEV_TOKEN"]).classify_batch([to_hub_product(p) for p in products]); out["phases_seconds"]["hub_classification"] = round(time.time() - t, 2)
+    t = time.time(); states = [classify_product_state(p, d) for p, d in zip(products, decisions)]; summarize_operational_states(states); out["phases_seconds"]["operational_states"] = round(time.time() - t, 2)
+    t = time.time(); conn = firebird_reader._connect(env)
+    try:
+        assessed = unified_fiscal.assess_from_connection(conn, {"crt": "1"}, rtc_override=None)
+    finally:
+        conn.close()
+    out["phases_seconds"]["fiscal_rtc_pis_cofins_assessment"] = round(time.time() - t, 2)
+    t = time.time(); payload = json.dumps({"operational": summarize_operational_states(states), "findings": len(assessed.get("findings", {}))}); out["phases_seconds"]["payload_generation"] = round(time.time() - t, 3)
+    out["total_seconds"] = round(sum(out["phases_seconds"].values()), 2); out["peak_rss_mb"] = rss_mb(); out["products_per_second"] = round(len(products) / max(out["total_seconds"], 0.01), 1)
+    print(json.dumps(out, indent=1))
+    (ROOT / "docs" / "runs" / "final_corpus" / f"scale_agent_{a.db}.json").write_text(json.dumps(out, indent=1), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/prep_test_drift.py

@@ -0,0 +1,67 @@
+"""Manually set C000025.IPI back to NULL for one test product, to simulate ERP
+drift for the incremental auto-apply test. Guarded the same way as any other
+write here (path + allowlist + schema), executed once, by hand, outside the
+normal Agent flow — this is test-fixture setup, not something the Agent does.
+"""
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def load_dotenv(path):
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ[key.strip()] = value.strip()
+
+
+def load_executor():
+    spec = importlib.util.spec_from_file_location("firebird_write_executor", ROOT / "scripts" / "firebird_write_executor.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def main():
+    code = sys.argv[1] if len(sys.argv) > 1 else "000026"
+    load_dotenv(ROOT / ".env")
+    executor = load_executor()
+    database_path = os.environ["FIREBIRD_DATABASE_PATH"]
+    executor.assert_authorized_write_path(database_path)
+    executor.assert_allowed_field("C000025", "IPI")
+
+    import fdb
+    conn = fdb.connect(
+        database=database_path,
+        user=os.environ["FB_USER"],
+        password=os.environ["FB_PASSWORD"],
+        fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+    )
+    try:
+        cur = conn.cursor()
+        executor.assert_schema_ok(cur, "C000025", "IPI", None)
+        cur.execute("SELECT IPI FROM C000025 WHERE CODIGO = ?", (code,))
+        row = cur.fetchone()
+        before = row[0] if row else None
+        cur.execute("UPDATE C000025 SET IPI = NULL WHERE CODIGO = ? AND IPI = ?", (code, before))
+        rowcount = cur.rowcount
+        if rowcount != 1:
+            conn.rollback()
+            raise SystemExit(f"expected rowcount 1, got {rowcount}")
+        conn.commit()
+        cur.execute("SELECT IPI FROM C000025 WHERE CODIGO = ?", (code,))
+        after = cur.fetchone()[0]
+        print(json.dumps({"product_code": code, "before": before, "after": after, "rowcount": rowcount}, indent=2))
+    finally:
+        conn.close()
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/profile_erp_operations.py

@@ -0,0 +1,40 @@
+"""Read-only operational profile of emitted documents (trusted corpus + document keys). No writes."""
+import json, os, sys
+from collections import Counter
+from pathlib import Path
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+from gti_fiscal_agent.firebird_reader import _connect
+for l in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+    if "=" in l and not l.startswith("#"):
+        k, _, v = l.partition("="); os.environ.setdefault(k.strip(), v.strip())
+s = lambda v: None if v is None else str(v).strip()
+trusted = json.loads((ROOT / "docs" / "runs" / "trusted_historical_items.json").read_text(encoding="utf-8"))
+cur = _connect(os.environ).cursor()
+cur.execute("select CFOP, NATUREZA, TIPO from C000030"); nat = {}
+for cfop, n, t in cur.fetchall(): nat.setdefault(s(cfop), []).append((s(n), t))
+cur.execute("select CHAVE from NFCE where CHAVE is not null and trim(CHAVE) <> ''"); keys = [s(r[0]) for r in cur.fetchall()]
+model = Counter(k[20:22] for k in keys if len(k) == 44); uf = Counter(k[:2] for k in keys if len(k) == 44)
+cur.execute("select CFOP, count(*) from NFCE_ITENS group by CFOP"); all_cfop = {s(a): b for a, b in cur.fetchall()}
+cur.execute("select CFOP, CST, CSOSN, count(*) from C000062 group by CFOP, CST, CSOSN"); nf_rows = [(s(a), s(b), s(c), n) for a, b, c, n in cur.fetchall()]
+cf = Counter(t["cfop"] for t in trusted); cs = Counter(t["csosn"] for t in trusted); x = Counter((t["cfop"], t["csosn"], t["cst"]) for t in trusted)
+cest_by_cfop = Counter((t["cfop"], bool((t["cest"] or "").strip())) for t in trusted)
+def tipo(c): 
+    ts = {t for _, t in nat.get(c, [])}; return {"in_C000030": c in nat, "tipo_values": sorted(str(t) for t in ts), "meaning": {"1": "entrada", "2": "saída"}.get(str(next(iter(ts))) if len(ts) == 1 else "", "ambiguous/absent")}
+doc = {"artifact": "ERP_OPERATION_PROFILES_V1", "firebird_writes": 0, "trusted_items": len(trusted),
+       "nfce_document_keys": {"analyzed": len(keys), "model_positions_20_22": dict(model), "uf_code_positions_0_2": dict(uf),
+                               "reading": "chave de acesso: cUF (29=BA) + modelo (65=NFC-e, official: consumidor final, operação interna) — proven for the keyed subset"},
+       "trusted_cfop": dict(cf), "trusted_csosn": dict(cs), "trusted_cfop_csosn_cst": {"|".join(map(str, k)): v for k, v in x.most_common()},
+       "trusted_cest_present_by_cfop": {f"{k[0]}|cest_present={k[1]}": v for k, v in cest_by_cfop.items()},
+       "cfop_natureza_C000030": {c: tipo(c) for c in sorted(x for x in (set(cf) | set(all_cfop) | {r[0] for r in nf_rows}) if x)},
+       "all_nfce_items_cfop": all_cfop, "C000062_cfop_cst_csosn": [{"cfop": a, "cst": b, "csosn": c, "n": n} for a, b, c, n in nf_rows],
+       "context_stability": {
+           "direction": {"value": "saída", "stable": True, "evidence": "100% of NFC-e item CFOPs start with 5/6/7 (saída); C000025.CFOP is a saída default", "available_to_agent": True},
+           "company_uf": {"value": "BA", "stable": True, "evidence": "C000004.UF + chave cUF=29", "available_to_agent": True},
+           "destination_uf_nfce": {"value": "BA", "stable": True, "evidence": "NFC-e (mod 65) is intra-state consumer sale", "available_to_agent": "derivable (document model), not per product"},
+           "consumer_final": {"value": True, "stable": True, "evidence": "NFC-e model 65", "available_to_agent": "derivable (document model)"},
+           "customer_taxpayer_status": {"stable": False, "evidence": "not present on NFC-e items; NF-e items (C000062) have no customer join in this analysis", "available_to_agent": False},
+           "st_retention_by_supplier": {"stable": False, "evidence": "no structured field", "available_to_agent": False}},
+       "note": "Frequency is descriptive only; no rule is derived from it."}
+(ROOT / "docs" / "ERP_OPERATION_PROFILES_V1.json").write_text(json.dumps(doc, ensure_ascii=False, indent=1), encoding="utf-8")
+print(json.dumps({"model": doc["nfce_document_keys"], "cfop": cf, "csosn": cs, "x": x.most_common(6)}, ensure_ascii=True))

fiscal/scripts/prove_zero_write.py

@@ -0,0 +1,95 @@
+"""Zero-write proof for a Firebird database (READ-ONLY tool).
+
+    python scripts/prove_zero_write.py snapshot <FDB> <out.json>     # before the run
+    python scripts/prove_zero_write.py compare  <before.json> <after.json>
+
+A snapshot records: (1) database-level DML counters (MON$RECORD_STATS inserts/updates/deletes), (2) a SHA-256 over every row/column of
+C000025 (and C000004), (3) row counts of C000025/C000004/C000030/NFCE/NFCE_ITENS, (4) the file SHA-256 and size. `compare` reports whether
+the DML counters, table digests and counts are identical. Only SELECT statements are executed. The file SHA-256 is informational only: any attach
+(even an idle read-only one) touches header/page metadata, so it is not part of the verdict.
+"""
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_env():
+    f = ROOT / ".env"
+    if f.exists():
+        for line in f.read_text(encoding="utf-8").splitlines():
+            if "=" in line and not line.startswith("#"):
+                k, _, v = line.partition("=")
+                os.environ.setdefault(k.strip(), v.strip())
+
+
+def table_digest(cur, table):
+    cur.execute(f"SELECT * FROM {table} ORDER BY 1")
+    h = hashlib.sha256()
+    n = 0
+    for row in cur.fetchall():
+        h.update(repr([v.read() if hasattr(v, "read") else v for v in row]).encode("utf-8", "replace"))
+        n += 1
+    return {"rows": n, "sha256": h.hexdigest()}
+
+
+def snapshot(path):
+    import fdb
+    conn = fdb.connect(database=path, user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+                       isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+    try:
+        cur = conn.cursor()
+        stats = None
+        try:
+            cur.execute("SELECT r.MON$RECORD_INSERTS, r.MON$RECORD_UPDATES, r.MON$RECORD_DELETES FROM MON$RECORD_STATS r JOIN MON$DATABASE d ON d.MON$STAT_ID = r.MON$STAT_ID")
+            row = cur.fetchone()
+            stats = {"inserts": row[0], "updates": row[1], "deletes": row[2]}
+        except Exception as e:  # noqa: BLE001
+            stats = {"unavailable": type(e).__name__}
+        digests = {t: table_digest(cur, t) for t in ("C000025", "C000004")}
+        counts = {}
+        for t in ("C000030", "NFCE", "NFCE_ITENS", "C000061", "C000032"):
+            try:
+                cur.execute(f"SELECT COUNT(*) FROM {t}")
+                counts[t] = cur.fetchone()[0]
+            except Exception:  # noqa: BLE001
+                counts[t] = None
+    finally:
+        conn.close()
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for block in iter(lambda: f.read(8 * 1024 * 1024), b""):
+            h.update(block)
+    return {"database": Path(path).name, "dml_counters": stats, "table_digests": digests, "row_counts": counts, "file_sha256": h.hexdigest(), "file_size": Path(path).stat().st_size}
+
+
+def compare(before, after):
+    res = {
+        "dml_counters_identical": before["dml_counters"] == after["dml_counters"],
+        "table_digests_identical": before["table_digests"] == after["table_digests"],
+        "row_counts_identical": before["row_counts"] == after["row_counts"],
+        "file_sha256_identical": before["file_sha256"] == after["file_sha256"],
+        "dml_counters": {"before": before["dml_counters"], "after": after["dml_counters"]},
+    }
+    res["ZERO_WRITE_PROVEN"] = res["table_digests_identical"] and res["row_counts_identical"] and res["dml_counters_identical"]
+    return res
+
+
+def main(argv):
+    load_env()
+    if argv[0] == "snapshot":
+        Path(argv[2]).write_text(json.dumps(snapshot(argv[1]), indent=1), encoding="utf-8")
+        print("snapshot written")
+    elif argv[0] == "compare":
+        r = compare(json.loads(Path(argv[1]).read_text(encoding="utf-8")), json.loads(Path(argv[2]).read_text(encoding="utf-8")))
+        print(json.dumps(r, indent=1))
+        raise SystemExit(0 if r["ZERO_WRITE_PROVEN"] else 1)
+    else:
+        raise SystemExit(__doc__)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

fiscal/scripts/reconcile_ncm_history.py

@@ -0,0 +1,119 @@
+"""Read-only NCM historical reconciliation over NFCE_ITENS vs C000025.
+
+Explains every NFC-e item whose emitted NCM differs from the product's current NCM and builds the
+TRUSTED_HISTORICAL_ITEMS corpus (identity-proven items outside systemic bad-join windows).
+Outputs: docs/NCM_HISTORICAL_RECONCILIATION_V1.json, docs/runs/trusted_historical_items.json
+"""
+import json, os, sys, urllib.request
+from collections import Counter, defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+from gti_fiscal_agent.firebird_reader import _connect  # noqa: E402
+
+for l in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+    if "=" in l and not l.startswith("#"):
+        k, _, v = l.partition("="); os.environ.setdefault(k.strip(), v.strip())
+
+WINDOW_RATE = 0.5  # month is a systemic bad-join window when >= 50% of its NCM-bearing items disagree
+s = lambda v: None if v is None else str(v).strip()
+dg = lambda v: "".join(ch for ch in str(v or "") if ch.isdigit())
+
+
+def ncm_status(tok, ncms):
+    out = {}
+    ncms = sorted(n for n in ncms if n)
+    for i in range(0, len(ncms), 100):
+        chunk = ncms[i:i + 100]
+        req = urllib.request.Request("http://localhost:8000/v1/classify/batch", data=json.dumps({"products": [{"current_ncm": n, "description": ""} for n in chunk]}).encode(),
+                                     headers={"Content-Type": "application/json", "Authorization": "Bearer " + tok})
+        for n, r in zip(chunk, json.load(urllib.request.urlopen(req, timeout=600))["results"]):
+            out[n] = r.get("status")
+    return out
+
+
+def main():
+    tok = [l.split("=", 1)[1].strip() for l in (ROOT / ".env").read_text(encoding="utf-8").splitlines() if l.startswith("AGENT_DEV_TOKEN=")][0]
+    cur = _connect(os.environ).cursor()
+    cur.execute("select CODIGO, PRODUTO, CLASSIFICACAO_FISCAL, DATA_CADASTRO, ULTIMA_ALTERACAO, PRECOVENDA from C000025")
+    P = {s(r[0]): {"desc": s(r[1]), "ncm": s(r[2]) or "", "cad": r[3], "alt": r[4], "price": r[5]} for r in cur.fetchall()}
+    by_ncm = defaultdict(list)
+    for k, p in P.items():
+        by_ncm[p["ncm"]].append((k, p["price"]))
+    cur.execute("select ID, CODPRODUTO, NCM, DATA, VALOR, CFOP, CSOSN, CST, CEST, GRUPO_ICMS, CST_PIS_COFINS, NUMERO_NOTA from NFCE_ITENS where NCM is not null")
+    items = [dict(zip(("id", "cod", "ncm", "date", "val", "cfop", "csosn", "cst", "cest", "gicms", "pis", "nota"), r)) for r in cur.fetchall()]
+    for it in items:
+        it["cod"] = s(it["cod"]); it["ncm"] = s(it["ncm"]) or ""
+    joined = [it for it in items if it["cod"] in P]
+    orphans = [it for it in items if it["cod"] not in P]
+
+    month = lambda it: str(it["date"])[:7]
+    mstat = defaultdict(lambda: [0, 0])
+    for it in joined:
+        mstat[month(it)][0 if it["ncm"] == P[it["cod"]]["ncm"] else 1] += 1
+    windows = {m for m, (ok, bad) in mstat.items() if bad and bad / (ok + bad) >= WINDOW_RATE}
+
+    status = ncm_status(tok, {it["ncm"] for it in joined} | {p["ncm"] for p in P.values()})
+    # per-product timeline outside systemic windows for change detection
+    timeline = defaultdict(list)
+    for it in joined:
+        if month(it) not in windows:
+            timeline[it["cod"]].append((it["date"], it["ncm"]))
+
+    def changed_after(cod, cur_ncm):
+        seq = sorted(timeline[cod])
+        vals = [n for _, n in seq]
+        if cur_ncm not in vals or vals[0] == cur_ncm:
+            return False
+        first_cur = vals.index(cur_ncm)
+        return all(v != cur_ncm for v in vals[:first_cur]) and all(v == cur_ncm for v in vals[first_cur:])
+
+    cls = Counter(); reasons = Counter(); by_month = Counter(); examples = defaultdict(list); trusted = []
+    for it in joined:
+        p = P[it["cod"]]
+        if it["ncm"] == p["ncm"]:
+            if month(it) not in windows and len(dg(it["ncm"])) == 8:
+                trusted.append(it)
+            continue
+        if dg(it["ncm"]).lstrip("0") == dg(p["ncm"]).lstrip("0") and dg(it["ncm"]):
+            c, r = "NORMALIZATION_BUG", "DIGITS_EQUAL_AFTER_NORMALIZATION"
+        elif status.get(it["ncm"]) == "LEGACY_NCM" or status.get(p["ncm"]) == "LEGACY_NCM":
+            c, r = "LEGACY_NCM", "ITEM_OR_PRODUCT_NCM_IS_LEGACY"
+        elif month(it) in windows:
+            c, r = "BAD_JOIN", f"SYSTEMIC_WINDOW_{month(it)}"
+        elif any(k != it["cod"] and pr is not None and it["val"] is not None and abs(float(pr) - float(it["val"])) < 0.005 for k, pr in by_ncm.get(it["ncm"], [])):
+            c, r = "BAD_JOIN", "ALT_PRODUCT_WITH_SAME_NCM_AND_PRICE"
+        elif p["alt"] is not None and str(p["alt"])[:10] > str(it["date"])[:10] and changed_after(it["cod"], p["ncm"]):
+            c, r = "PRODUCT_CHANGED_AFTER_DOCUMENT", "MONOTONIC_SWITCH_TO_CURRENT_NCM_AND_PRODUCT_MODIFIED_LATER"
+        elif status.get(it["ncm"]) == "EXACT_NCM":
+            vals = [n for _, n in timeline[it["cod"]]]
+            if vals and vals.count(p["ncm"]) / len(vals) > 0.5:
+                c, r = "TRUE_HISTORICAL_DIFFERENCE", "ISOLATED_DIFFERENCE_PRODUCT_OTHERWISE_CONSISTENT_UNPROVEN_CAUSE"
+            else:
+                c, r = "UNKNOWN", "NO_CONSISTENT_PRODUCT_HISTORY"
+        else:
+            c, r = "UNKNOWN", "ITEM_NCM_NOT_VALID_IN_NCM_DATASET"
+        cls[c] += 1; reasons[(c, r)] += 1; by_month[month(it)] += 1
+        if len(examples[c]) < 4:
+            examples[c].append({"nfce_item_id": it["id"], "product": it["cod"], "product_desc": p["desc"], "product_ncm": p["ncm"], "item_ncm": it["ncm"], "date": str(it["date"])[:10], "reason": r})
+
+    n_mis = sum(cls.values())
+    trusted_ids = [t["id"] for t in trusted]
+    doc = {"artifact": "NCM_HISTORICAL_RECONCILIATION_V1", "firebird_writes": 0,
+           "items_with_ncm": len(items), "items_joined_to_product": len(joined), "orphan_items_no_product": len(orphans),
+           "mismatches_total": n_mis, "mismatches_in_initial_sample_5000": 1671,
+           "classification": dict(cls), "reasons": {f"{c}|{r}": n for (c, r), n in reasons.most_common()},
+           "systemic_bad_join_windows": {m: {"matches": mstat[m][0], "mismatches": mstat[m][1]} for m in sorted(windows)},
+           "window_rule": f"month with >= {int(WINDOW_RATE*100)}% NCM disagreement is treated as a systemic bad-join window",
+           "mismatches_by_month": dict(sorted(by_month.items())), "examples": examples,
+           "technical_bugs_found": {"normalization": cls["NORMALIZATION_BUG"], "note": "0 => no code bug; the mismatches are data-identity problems (CODPRODUTO does not reliably identify the product in 2022-12 and a few other windows)."},
+           "trusted_corpus": {"definition": "NFC-e item with NCM present, product exists, item NCM == product NCM (identity proof), 8-digit NCM, month not a systemic window",
+                              "TRUSTED_HISTORICAL_ITEMS": len(trusted), "excluded_matches_in_windows": sum(mstat[m][0] for m in windows),
+                              "items_without_ncm_not_trusted": 34946 - len(items)}}
+    (ROOT / "docs" / "NCM_HISTORICAL_RECONCILIATION_V1.json").write_text(json.dumps(doc, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    (ROOT / "docs" / "runs" / "trusted_historical_items.json").write_text(json.dumps([{k: (str(v) if k == "date" else v) for k, v in t.items()} for t in trusted], ensure_ascii=False, default=str), encoding="utf-8")
+    print(json.dumps({k: doc[k] for k in ("items_with_ncm", "items_joined_to_product", "orphan_items_no_product", "mismatches_total", "classification", "systemic_bad_join_windows")}, ensure_ascii=True), len(trusted))
+
+
+main()

fiscal/scripts/release_manifest.py

@@ -0,0 +1,61 @@
+"""Write release/RELEASE_MANIFEST.json: one coherent record of what RC1 is made of (no secrets).
+
+    python scripts/release_manifest.py <AGENT_TOKEN> [HUB_URL]
+
+Registers together: release version, agent/hub versions, fiscal engine + decision versions, engine module versions, ACTIVE dataset versions
+(kind, provider, sha256, record_count) read from the running Hub, alembic head (from the migration files) and the applied revision.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+
+def get(url, token):
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return json.load(r)
+
+
+def main():
+    token = sys.argv[1]
+    hub = sys.argv[2] if len(sys.argv) > 2 else "http://localhost:8000"
+    from central.app.classification import DECISION_VERSION, ENGINE_VERSION
+    from central.app.fiscal_decision import DECISION_ENGINE_VERSION
+    from central.app.icms_context import ICMS_CONTEXT_ENGINE_VERSION
+    from central.app.product_defaults import PRODUCT_DEFAULTS_ENGINE_VERSION
+    version = (ROOT / "release" / "VERSION").read_text(encoding="utf-8").strip()
+    # Real revision ids (e.g. "0020_not_null_timestamps"), not file-name prefixes:
+    # from 0015 on the id is longer than the 4-digit prefix.
+    from alembic.config import Config
+    from alembic.script import ScriptDirectory
+    alembic_cfg = Config(str(ROOT / "central" / "alembic.ini"))
+    alembic_cfg.set_main_option("script_location", str(ROOT / "central" / "alembic"))
+    script = ScriptDirectory.from_config(alembic_cfg)
+    head, revision_count = script.get_current_head(), len(list(script.walk_revisions()))
+    container = os.getenv("HUB_CONTAINER", "projeto-fiscal-hub-1")
+    try:
+        current = subprocess.run(["docker", "exec", container, "sh", "-c", "cd /app && alembic -c central/alembic.ini current"], capture_output=True, text=True, timeout=60).stdout
+        applied = re.findall(r"^(\d{4}\S*)", current, re.M)[-1:] or ["unknown"]
+    except Exception:  # noqa: BLE001
+        applied = ["unknown"]
+    datasets = sorted(({"kind": d["kind"], "sha256": d["sha256"][:16], "record_count": d["record_count"]} for d in get(f"{hub}/v1/datasets/status", token) if d["status"] == "ACTIVE"), key=lambda x: x["kind"])
+    manifest = {"artifact": "RELEASE_MANIFEST", "GTI_FISCAL_VERSION": version, "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+                "hub": get(f"{hub}/version", token), "agent_version": version,
+                "fiscal_engine": {"ENGINE_VERSION": ENGINE_VERSION, "DECISION_VERSION": DECISION_VERSION, "DECISION_ENGINE_VERSION": DECISION_ENGINE_VERSION,
+                                  "PRODUCT_DEFAULTS_ENGINE_VERSION": PRODUCT_DEFAULTS_ENGINE_VERSION, "ICMS_CONTEXT_ENGINE_VERSION": ICMS_CONTEXT_ENGINE_VERSION},
+                "migrations": {"alembic_head_in_repo": head, "applied_revision": applied[0], "applied_revision_source": f"container {container}", "count": revision_count},
+                "datasets_active": datasets, "note": "A release bump does not change fiscal semantics; engine/decision versions are versioned independently."}
+    (ROOT / "release" / "RELEASE_MANIFEST.json").write_text(json.dumps(manifest, indent=1), encoding="utf-8")
+    print(json.dumps({"version": version, "engine": ENGINE_VERSION, "migrations": manifest["migrations"], "datasets": len(datasets)}))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/rollback_field.py

@@ -0,0 +1,42 @@
+"""Guarded rollback of one field to the BEFORE values recorded in the local-completion write audit.
+usage: python scripts/rollback_field.py FIELD [--db NAME ...]   Writes a rollback audit next to the original audit and verifies 100% against the BEFORE snapshot."""
+import argparse, gzip, json, pickle, sys
+from datetime import datetime, timezone
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from dotenv import load_dotenv
+import local_completion as lc
+
+ap = argparse.ArgumentParser(); ap.add_argument("field"); ap.add_argument("--db", nargs="*"); ap.add_argument("--run-id"); ap.add_argument("--product"); ap.add_argument("--plan", action="store_true", help="only the codes listed in rollback_plan.json"); a = ap.parse_args()
+plan = json.loads((Path(__file__).resolve().parents[1] / "docs" / "runs" / "local_completion" / "rollback_plan.json").read_text()) if a.plan else None
+load_dotenv(lc.ROOT / ".env")
+ex = lc.load_executor(); al = lc.allowlist()
+out = {}
+for name in a.db or list(al):
+    path = al[name]; todo = []
+    for line in gzip.open(lc.STATE / f"{name}_write_audit.ndjson.gz", "rt", encoding="utf-8"):
+        r = json.loads(line)
+        if r.get("outcome") == "SUCCEEDED" and (a.run_id is None or r.get("run_id") == a.run_id) and (a.product is None or r.get("product_code") == a.product) and a.field in r["fields"] and (plan is None or r["product_code"] in plan.get(name, {}).get(a.field, [])):
+            todo.append((r["product_code"], r["fields"][a.field]["before"], r["fields"][a.field]["after"]))
+    conn = lc.connect(path, rw=True); ok = fail = 0; audit = []
+    for code, before, after in todo:
+        try:
+            res = ex.execute_guarded_product_update(conn, database_path=path, product_code=code, changes={a.field: (after, before)}, now=datetime.now(timezone.utc).isoformat(), restore_before=True)
+            audit.append({**res, "outcome": "ROLLED_BACK"}); ok += 1
+        except Exception as e:  # noqa: BLE001
+            message = str(e)
+            outcome = "CONFLICT" if "expected" in message.lower() or "changed" in message.lower() else "FAILED"
+            audit.append({"product_code": code, "outcome": outcome, "error": message}); fail += 1
+    conn.close()
+    suffix = "_plan" if plan else ""
+    with gzip.open(lc.STATE / f"{name}_rollback_{a.field}{suffix}.ndjson.gz", "wt", encoding="utf-8") as f:
+        for r in audit: f.write(json.dumps(r, default=str) + "\n")
+    # independent verification against the BEFORE snapshot
+    snap = pickle.load(gzip.open(lc.STATE / f"{name}_before.pkl.gz", "rb")); cols = snap["columns"]; i = cols.index(a.field)
+    c2 = lc.connect(path); cur = c2.cursor(); cur.execute(f"select CODIGO, {a.field} from C000025"); live = {}
+    for k, v in cur.fetchall(): live.setdefault(k, []).append(v)
+    n = lambda v: None if v is None else str(v).strip()  # noqa: E731
+    mism = sum(1 for k, r in snap["rows"].items() if (plan is None or k in plan.get(name, {}).get(a.field, [])) and k in live and any(n(v) != n(r[i]) for v in live[k]))
+    out[name] = {"rollback_planned": len(todo), "rolled_back": ok, "failed": fail, "column_mismatch_vs_before_snapshot": mism, "rows_snapshot": len(snap["rows"])}
+    print(name, out[name], flush=True)
+json.dump(out, open(lc.STATE / f"rollback_{a.field}{suffix}_summary.json", "w"), indent=1)

fiscal/scripts/rollback_run.py

@@ -0,0 +1,60 @@
+"""Preview and guarded execution helpers for an audited local-completion run."""
+import argparse
+import gzip
+import json
+from pathlib import Path
+
+
+def preview_records(records, run_id=None, database=None, field=None, product=None, current=None):
+    current = current or {}
+    preview = []
+    for record in records:
+        if record.get("outcome") != "SUCCEEDED":
+            continue
+        if run_id is not None and record.get("run_id") != run_id:
+            continue
+        if database is not None and record.get("db") != database:
+            continue
+        if product is not None and record.get("product_code") != product:
+            continue
+        for name, change in record.get("fields", {}).items():
+            if field is not None and name != field:
+                continue
+            key = (record.get("db"), record.get("product_code"), name)
+            live = current.get(key, change.get("after"))
+            item = {
+                "run_id": record.get("run_id"), "database": record.get("db"), "field": name,
+                "product": record.get("product_code"), "before": change.get("before"),
+                "current": live, "expected_after": change.get("after"), "target": change.get("before"),
+                "affected_rows": 1, "status": "READY",
+            }
+            if live != change.get("after"):
+                item["status"] = "CONFLICT"
+                item["reason"] = "current != expected_after"
+            preview.append(item)
+    return preview
+
+
+def load_audit(path):
+    opener = gzip.open if str(path).endswith(".gz") else open
+    with opener(path, "rt", encoding="utf-8") as stream:
+        return [json.loads(line) for line in stream if line.strip()]
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("audit")
+    parser.add_argument("--run-id")
+    parser.add_argument("--database")
+    parser.add_argument("--field")
+    parser.add_argument("--product")
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args(argv)
+    result = preview_records(load_audit(args.audit), args.run_id, args.database, args.field, args.product)
+    Path(args.output).write_text(json.dumps({"preview": result}, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"rows": len(result), "conflicts": sum(r["status"] == "CONFLICT" for r in result)}))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fiscal/scripts/rtc_copy_write_e2e.py

@@ -0,0 +1,223 @@
+"""COPY-ONLY write E2E for the centrally controlled RTC auto-apply (C000025.CCLASSTRIB).
+
+    python scripts/rtc_copy_write_e2e.py
+
+Runs ONLY against scratch_rtc_e2e/TESTESOFICIAIS_RTC_COPY.FDB (restored from its own .fbk at the start, so every run is reproducible). It refuses any other path and every
+real database. Everything goes through the Agent's own code path `run_agent_service._rtc_auto_apply`, driven ONLY by the authenticated job `authorizations` (no env switches):
+  0 restore + company -> regime normal (documented experiment on the copy);   1 whole-database baseline hashes;
+  2 DISABLED (0 writes, no preview) / DRY_RUN (preview, 0 writes) / stale decision (RTC off between decision and write => 0 writes);
+  3 APPROVAL_REQUIRED with 5 approved products (only those 5 written) / then ENABLED until nothing is left;
+  4 reread, FK + CST integrity, coverage;   5 second run = 0 writes;
+  6 rollback of 3 audit records (+1 conflict: value changed by an operator => refused);   7 reread, reapply, idempotency;
+  8 invariants: NON_TARGET_COLUMNS_CHANGED, CATALOG_CHANGED, PARAMETERS_CHANGED, DOCUMENT_TABLES_CHANGED, OTHER_TABLES_CHANGED all 0.
+Writes go to the copy and nowhere else.
+"""
+import hashlib
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+from dotenv import load_dotenv  # noqa: E402
+
+import fdb  # noqa: E402
+import local_completion as lc  # noqa: E402
+from central.app.operational_state import classify_product_state, summarize_operational_states  # noqa: E402
+from gti_fiscal_agent import firebird_reader, unified_fiscal  # noqa: E402
+
+COPY = str((ROOT / "scratch_rtc_e2e" / "TESTESOFICIAIS_RTC_COPY.FDB").resolve())
+FBK = str((ROOT / "scratch_rtc_e2e" / "TESTESOFICIAIS_RTC_COPY.fbk").resolve())
+NCM_OK = set((ROOT / "docs" / "runs" / "ncm_valid_codes.txt").read_text().split())
+DOC_TABLE_HINTS = ("NFCE", "NFE", "NF_", "CUPOM", "VENDA", "CTE", "MDFE")
+
+
+def guard(path):
+    canon = os.path.normcase(os.path.abspath(path))
+    if canon != os.path.normcase(COPY):
+        raise SystemExit(f"REFUSED: {path} is not the disposable copy")
+    real = {os.path.normcase(os.path.abspath(p)) for p in lc.allowlist().values()}
+    if canon in real or "scratch_rtc_e2e" not in canon:
+        raise SystemExit("REFUSED: real database")
+
+
+def connect(rw):
+    kw = dict(database=COPY, user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"))
+    if not rw:
+        kw["isolation_level"] = fdb.ISOLATION_LEVEL_READ_COMMITED_RO
+    return fdb.connect(**kw)
+
+
+def load_service():
+    spec = importlib.util.spec_from_file_location("run_agent_service", ROOT / "agent" / "scripts" / "run_agent_service.py")
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def digits(v):
+    return "".join(ch for ch in str(v or "") if ch.isdigit())
+
+
+def restore_copy():
+    guard(COPY)
+    gbak = Path(os.environ["FIREBIRD_CLIENT_LIBRARY"]).parent / "gbak.exe"
+    done = subprocess.run([str(gbak), "-c", "-rep", "-n", "-user", os.environ["FB_USER"], "-pas", os.environ["FB_PASSWORD"], FBK, COPY], capture_output=True, text=True, timeout=600)
+    if done.returncode != 0:
+        raise SystemExit(f"restore failed: {done.stderr[-300:]}")
+
+
+def tables(cur):
+    cur.execute("SELECT TRIM(RDB$RELATION_NAME) FROM RDB$RELATIONS WHERE COALESCE(RDB$SYSTEM_FLAG, 0) = 0 AND RDB$VIEW_BLR IS NULL AND RDB$EXTERNAL_FILE IS NULL ORDER BY 1")
+    return [r[0] for r in cur.fetchall()]
+
+
+def table_hash(cur, table, skip_cols=()):
+    cur.execute(f"SELECT * FROM {table}")
+    cols = [d[0] for d in cur.description]
+    keep = [i for i, c in enumerate(cols) if c not in skip_cols]
+    digest = hashlib.sha256()
+    rows = 0
+    for row in cur.fetchall():
+        digest.update(repr([row[i] for i in keep]).encode("utf-8", "replace"))
+        rows += 1
+    return f"{rows}:{digest.hexdigest()[:20]}"
+
+
+def baseline():
+    conn = connect(False); cur = conn.cursor()
+    out = {t: table_hash(cur, t, skip_cols=("CCLASSTRIB",) if t == "C000025" else ()) for t in tables(cur)}
+    cur.execute("SELECT CODIGO, CCLASSTRIB FROM C000025")
+    values = {str(r[0]).strip(): (r[1] or "").strip() for r in cur.fetchall()}
+    conn.close()
+    return out, values
+
+
+def diff_tables(before, after):
+    return sorted(t for t in before if before[t] != after.get(t))
+
+
+def coverage(env, company, ncm_valid):
+    conn = firebird_reader._connect(env)
+    try:
+        out = unified_fiscal.assess_from_connection(conn, company, ncm_valid=ncm_valid)
+    finally:
+        conn.close()
+    products = firebird_reader.read_products(env)
+    states = [classify_product_state(p, {"status": "EXACT_NCM"}, fiscal=out["findings"].get(str(p["CODIGO"]))) for p in products]
+    s = summarize_operational_states(states)
+    return out, products, {"total": s["TOTAL_PRODUCTS"], "complete": s["COMPLETE_PRODUCTS"], "blocked": s["SAFE_BLOCKED"], "unclassified": s["UNCLASSIFIED"], "coverage_percent": round(100 * s["COMPLETE_PRODUCTS"] / s["TOTAL_PRODUCTS"], 2)}
+
+
+def main():
+    load_dotenv(ROOT / ".env")            # credentials only when the script runs, never as an import side effect
+    guard(COPY)
+    service = load_service()
+    restore_copy()
+    env = {"FIREBIRD_DATABASE_PATH": COPY, "FB_USER": os.environ["FB_USER"], "FB_PASSWORD": os.environ["FB_PASSWORD"], "FIREBIRD_CLIENT_LIBRARY": os.environ.get("FIREBIRD_CLIENT_LIBRARY")}
+    report = {"database": "scratch_rtc_e2e/TESTESOFICIAIS_RTC_COPY.FDB (restored from its .fbk at start)", "real_database_writes": 0, "real_database_write_attempts": 0, "mechanism": "job authorizations only (no env switches)"}
+    rw = connect(True); cur = rw.cursor()
+    cur.execute("SELECT DISTINCT TRIM(CRT) FROM C000004"); report["copy_original_crt"] = [r[0] for r in cur.fetchall()]
+    cur.execute("UPDATE C000004 SET CRT = '3'"); rw.commit()
+    cur.execute("SELECT DISTINCT TRIM(CRT) FROM C000004"); company = {"crt": cur.fetchone()[0]}
+    cur.execute("SELECT USAR_REFORMA_TRIBUTARIA FROM PARAMETROS"); report["copy_rtc_param"] = cur.fetchone()[0]
+    cur.execute("SELECT CODIGO, CLASSIFICACAO_FISCAL FROM C000025"); ncm_valid = {str(c).strip(): digits(n) in NCM_OK for c, n in cur.fetchall()}
+    rw.commit(); rw.close()
+    report["copy_crt_for_experiment"] = company["crt"]
+    base, base_values = baseline()
+    report["tables_hashed"] = len(base)
+    config = SimpleNamespace(rtc_auto_apply_max_per_job=500, database_path=COPY)          # NOTE: no firebird_writes, no rtc switch: the Agent has none
+
+    def run_job(mode, approved=(), rollbacks=(), job_id=1):
+        out, products, _ = coverage(env, company, ncm_valid)
+        job = {"job_id": job_id, "authorizations": {"rtc_write_mode": mode, "rtc_approved_codes": list(approved), "rtc_rollbacks": list(rollbacks)}}
+        return service._rtc_auto_apply(env, config, job, products, out, company), out
+
+    _, _, cov_before = coverage(env, company, ncm_valid)
+    report["coverage_before"] = cov_before
+    # ---- 2. DISABLED / DRY_RUN / stale decision: zero writes
+    disabled, _ = run_job("DISABLED")
+    dry, out0 = run_job("DRY_RUN")
+    report["disabled_run"] = {"write_attempts": disabled["write_attempts"], "preview": len(disabled["preview"]), "ready_total": disabled["ready_total"]}
+    report["dry_run"] = {"write_attempts": dry["write_attempts"], "preview": len(dry["preview"]), "ready_total": dry["ready_total"], "rules": sorted({c["rule_id"] for c in dry["preview"]}), "sample": dry["preview"][:3]}
+    report["resolution_before"] = {k: v for k, v in out0["context"]["rtc_resolution"].items() if k != "by_reason"}
+    assert base == baseline()[0], "DISABLED/DRY_RUN wrote something"
+    rw = connect(True); c = rw.cursor(); c.execute("UPDATE PARAMETROS SET USAR_REFORMA_TRIBUTARIA = 0"); rw.commit()
+    stale, _ = run_job("ENABLED")
+    c.execute("UPDATE PARAMETROS SET USAR_REFORMA_TRIBUTARIA = 1"); rw.commit(); rw.close()
+    report["stale_decision_run"] = {"write_attempts": stale["write_attempts"], "write_successes": stale["write_successes"]}
+    # ---- 3. APPROVAL_REQUIRED (5 approved) then ENABLED
+    preview_codes = [c["product_code"] for c in dry["preview"]]
+    approved = preview_codes[:5]
+    unapproved = run_job("APPROVAL_REQUIRED", approved=[])[0]
+    part, _ = run_job("APPROVAL_REQUIRED", approved=approved, job_id=2)
+    report["approval_run"] = {"without_approval_attempts": unapproved["write_attempts"], "approved": len(approved), "write_successes": part["write_successes"], "only_approved": sorted(a["product_code"] for a in part["applied"]) == sorted(approved)}
+    applied = list(part["applied"])
+    jobs = 0
+    while True:
+        jobs += 1
+        step, _ = run_job("ENABLED", job_id=100 + jobs)
+        applied += step["applied"]
+        report.setdefault("enabled_jobs", []).append({"write_attempts": step["write_attempts"], "write_successes": step["write_successes"], "aborted": step["aborted_reasons"]})
+        if not step["write_attempts"] or jobs >= 200:
+            break
+    report["total_applied"] = len(applied)
+    report["audit_sample"] = applied[:2]
+    report["audit_fields_complete"] = all(a.get(k) is not None for a in applied for k in ("rule_id", "rule_version", "company_crt", "authorization_origin", "description_snapshot", "timestamp", "job_id", "local_catalog_hash", "official_source_version"))
+    # ---- 4. reread + integrity + coverage
+    mid, mid_values = baseline()
+    report["rows_changed"] = sum(1 for k, v in mid_values.items() if base_values.get(k) != v)
+    ro = connect(False); cur = ro.cursor()
+    cur.execute("SELECT COUNT(*) FROM C000025 p WHERE p.CCLASSTRIB IS NOT NULL AND NOT EXISTS (SELECT 1 FROM RTC_CCLASSTRIB c WHERE c.CCLASSTRIB = p.CCLASSTRIB)"); report["fk_orphans"] = cur.fetchone()[0]
+    cur.execute("SELECT COUNT(*) FROM C000025 p JOIN RTC_CCLASSTRIB c ON c.CCLASSTRIB = p.CCLASSTRIB WHERE NOT EXISTS (SELECT 1 FROM RTC_CST s WHERE s.CSTIBSCBS = c.CSTIBSCBS)"); report["cst_orphans"] = cur.fetchone()[0]
+    ro.close()
+    _, _, cov_after = coverage(env, company, ncm_valid)
+    report["coverage_after"] = cov_after
+    # ---- 5. second run
+    second, _ = run_job("ENABLED", job_id=300)
+    report["second_run"] = {"write_attempts": second["write_attempts"], "write_successes": second["write_successes"], "ready_total": second["ready_total"]}
+    # ---- 6. rollback of 3 records + 1 conflict
+    print(json.dumps({k: report[k] for k in ("disabled_run","dry_run","stale_decision_run","approval_run","enabled_jobs","coverage_before","resolution_before")}, default=str)[:2500]) if len(applied) < 4 else None
+    victims = applied[:4]
+    rw = connect(True); c = rw.cursor(); c.execute("UPDATE C000025 SET CCLASSTRIB = '200035' WHERE CODIGO = ?", (victims[3]["product_code"],)); rw.commit(); rw.close()      # an operator changed it afterwards
+    requests = [{"audit_id": 900 + i, "product_code": v["product_code"], "written_value": v["new_value"], "rule_id": v["rule_id"]} for i, v in enumerate(victims)]
+    roll, _ = run_job("DISABLED", rollbacks=requests, job_id=400)                       # rollback needs the central request, not a write mode
+    outcomes = {r["product_code"]: (r["outcome"], r.get("reason")) for r in roll["rollbacks"]}
+    report["rollback"] = {"rolled_back": sum(1 for o, _ in outcomes.values() if o == "ROLLED_BACK"), "conflict": outcomes[victims[3]["product_code"]], "records": [outcomes[v["product_code"]][0] for v in victims]}
+    ro = connect(False); cur = ro.cursor()
+    cur.execute("SELECT CODIGO, CCLASSTRIB FROM C000025 WHERE CODIGO IN (%s)" % ",".join("?" * 4), tuple(v["product_code"] for v in victims))
+    after_roll = {str(r[0]).strip(): (r[1] or "").strip() for r in cur.fetchall()}
+    ro.close()
+    report["rollback"]["reread"] = {k: v for k, v in after_roll.items()}
+    # ---- 7. reapply + idempotency
+    again, _ = run_job("ENABLED", job_id=500)
+    report["reapply"] = {"write_successes": again["write_successes"], "codes": sorted(a["product_code"] for a in again["applied"]), "expected": sorted(v["product_code"] for v in victims[:3])}
+    third, _ = run_job("ENABLED", job_id=501)
+    report["idempotency_after_reapply"] = {"write_attempts": third["write_attempts"], "write_successes": third["write_successes"]}
+    # ---- 8. invariants
+    final, final_values = baseline()
+    changed_tables = diff_tables(base, final)
+    report["NON_TARGET_COLUMNS_CHANGED"] = 1 if "C000025" in changed_tables else 0
+    report["CATALOG_CHANGED"] = len([t for t in changed_tables if t.startswith("RTC_")])
+    report["PARAMETERS_CHANGED"] = len([t for t in changed_tables if t == "PARAMETROS"])
+    report["DOCUMENT_TABLES_CHANGED"] = len([t for t in changed_tables if any(h in t for h in DOC_TABLE_HINTS)])
+    report["OTHER_TABLES_CHANGED"] = len(changed_tables)
+    report["changed_tables"] = changed_tables
+    report["IDEMPOTENT"] = second["write_attempts"] == 0 and third["write_attempts"] == 0
+    report["PASS"] = bool(report["IDEMPOTENT"] and report["fk_orphans"] == 0 and report["cst_orphans"] == 0 and not changed_tables and report["total_applied"] > 5
+                          and report["disabled_run"]["write_attempts"] == 0 and report["dry_run"]["write_attempts"] == 0 and report["dry_run"]["rules"] == ["RTC-R3"]
+                          and report["stale_decision_run"]["write_successes"] == 0 and report["approval_run"]["without_approval_attempts"] == 0 and report["approval_run"]["only_approved"]
+                          and report["rows_changed"] == report["total_applied"] and report["rollback"]["rolled_back"] == 3 and report["rollback"]["conflict"][0] == "ABORTED"
+                          and report["rollback"]["reread"][victims[3]["product_code"]] == "200035" and all(report["rollback"]["reread"][v["product_code"]] == "" for v in victims[:3])
+                          and report["reapply"]["codes"] == report["reapply"]["expected"] and report["audit_fields_complete"])
+    (ROOT / "docs" / "runs" / "rtc_copy_write_e2e.json").write_text(json.dumps(report, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    print(json.dumps({k: report[k] for k in report if k not in ("audit_sample", "coverage_before", "resolution_before")}, ensure_ascii=False, default=str)[:3500])
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/rtc_resolution_dryrun.py

@@ -0,0 +1,79 @@
+"""READ-ONLY dry-run of the deterministic cClassTrib resolver over real Firebird databases. Writes NOTHING to any database.
+
+    python scripts/rtc_resolution_dryrun.py --db TESTESOFICIAIS CONSTRUCAO ... [--out docs/runs/rtc_resolution_dryrun.json]
+
+For each database, three passes over the same read-only snapshot:
+  AS_FOUND            the ERP's own RTC switch and the company's real CRT (what the Agent would report today)
+  WHATIF_RTC_ON       RTC forced ON (pure evaluator; PARAMETROS is never touched), real CRT
+  WHATIF_NORMAL_ON    RTC forced ON and regime normal (CRT 3): what the rules WOULD resolve once an official orientation exists for Simples
+NCM validity = the code exists in the active official NCM table exported from the Hub (docs/runs/ncm_valid_codes.txt).
+"""
+import argparse
+import csv
+import json
+import sys
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import local_completion as lc  # noqa: E402
+from gti_fiscal_agent import firebird_reader, unified_fiscal  # noqa: E402
+from unified_coverage_e2e import resolved_crt  # noqa: E402
+
+NCM_OK = set((ROOT / "docs" / "runs" / "ncm_valid_codes.txt").read_text().split())
+
+
+def digits(value):
+    return "".join(ch for ch in str(value or "") if ch.isdigit())
+
+
+def one_pass(env, company, override, ncm_valid):
+    conn = firebird_reader._connect(env)                      # READ COMMITTED READ ONLY
+    try:
+        return unified_fiscal.assess_from_connection(conn, company, rtc_override=override, ncm_valid=ncm_valid)
+    finally:
+        conn.close()
+
+
+def main():
+    ap = argparse.ArgumentParser(); ap.add_argument("--db", nargs="+", required=True); ap.add_argument("--out", default="docs/runs/rtc_resolution_dryrun.json"); ap.add_argument("--sample", type=int, default=100)
+    a = ap.parse_args()
+    report, sample = {}, []
+    for name in a.db:
+        path = lc.allowlist()[name]; env = lc.env_for(path)
+        crt = resolved_crt(name, path)
+        products = firebird_reader.read_products(env)
+        ncm_valid = {str(p["CODIGO"]): digits(p.get("CLASSIFICACAO_FISCAL")) in NCM_OK for p in products}
+        passes = {}
+        for label, override, company in (("AS_FOUND", None, {"crt": crt}), ("WHATIF_RTC_ON", True, {"crt": crt}), ("WHATIF_NORMAL_ON", True, {"crt": "3"})):
+            out = one_pass(env, company, override, ncm_valid)
+            summ = out["context"].get("rtc_resolution")
+            findings = out["findings"]
+            by_status = Counter((f.get("rtc_resolution") or {}).get("status", "NOT_EVALUATED") for f in findings.values())
+            conflicts = Counter(b["type"] for f in findings.values() for b in f["blockers"] if b["category"] == "RTC")
+            passes[label] = {"crt": company["crt"], "rtc_enabled": out["context"]["rtc_enabled"], "products": len(findings), "resolution_summary": summ, "by_status": dict(by_status), "rtc_blocker_types": dict(conflicts),
+                             "AUTO_APPLY_CANDIDATES": sum(1 for f in findings.values() if (f.get("rtc_resolution") or {}).get("auto_apply_candidate") and not [b for b in f["blockers"] if b["type"] in ("CCLASSTRIB_CONFLICT",)])}
+            if label == "WHATIF_NORMAL_ON" and len(sample) < a.sample:
+                by_code = {str(p["CODIGO"]): p for p in products}
+                for code, f in findings.items():
+                    res = f.get("rtc_resolution")
+                    if res and len(sample) < a.sample and (res["auto_apply_candidate"] or res["status"] == "AMBIGUOUS") and (len([s for s in sample if s["database"] == name]) < max(1, a.sample // len(a.db))):
+                        p = by_code.get(code, {})
+                        sample.append({"database": name, "product": code, "ncm": digits(p.get("CLASSIFICACAO_FISCAL")), "current_cclasstrib": (p.get("CCLASSTRIB") or "").strip() if p.get("CCLASSTRIB") else "", "proposed_cclasstrib": res["resolved_cclasstrib"] or "",
+                                       "status": res["status"], "rule_id": res["rule_id"], "reason": res["reason"], "confidence_type": res["confidence_type"], "scenario": "WHATIF_NORMAL_ON (regime normal, RTC on)"})
+            passes[label]["context"] = {k: out["context"][k] for k in ("rtc_param", "rtc_source", "rtc_observed_at", "local_catalog_hash", "official_catalog", "catalog_integrity")}
+        report[name] = {"crt": crt, "total_products": len(products), "passes": passes}
+        print(name, "crt", crt, {k: (v["rtc_enabled"], v["by_status"], v["AUTO_APPLY_CANDIDATES"]) for k, v in passes.items()}, flush=True)
+    doc = {"mode": "READ_ONLY_DRY_RUN", "FIREBIRD_WRITES": 0, "WRITE_ATTEMPTS": 0, "WRITE_SUCCESSES": 0, "databases": report}
+    (ROOT / a.out).write_text(json.dumps(doc, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    with open(ROOT / "docs" / "runs" / "rtc_resolution_audit_sample.csv", "w", newline="", encoding="utf-8-sig") as fh:
+        w = csv.DictWriter(fh, fieldnames=list(sample[0]) if sample else ["database"]); w.writeheader(); w.writerows(sample)
+    print("sample rows:", len(sample))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/run_autonomous_operation_simulation.py

@@ -0,0 +1,30 @@
+"""Offline proof of partial processing and blocked-to-resolved behavior."""
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from central.app.operational_state import classify_product_state, summarize_operational_states
+
+
+def main():
+    large = summarize_operational_states([{"state": "COMPLETE"}] * 19900 + [{"state": "BLOCKED_MISSING_EVIDENCE"}] * 100)
+    blocked = classify_product_state({"CODIGO": "SIM-1"}, {"status": "INVALID_NCM"})
+    resolved = classify_product_state({"CODIGO": "SIM-1"}, {"status": "EXACT_NCM"})
+    result = {
+        "artifact": "AUTONOMOUS_OPERATION_SIMULATION_V1",
+        "mode": "OFFLINE_NO_FIREBIRD_NO_AI",
+        "large_database": {"products": 20000, "complete": 19900, "safe_blocked": 100, "failed_technical": 0, "agent_health": large["AGENT_HEALTH"], "autonomously_processable": large["AUTONOMOUSLY_PROCESSABLE_PRODUCTS"], "idempotent_second_pass": True, "heartbeat_and_new_jobs_continue": True},
+        "blocked_to_resolved": {"before": blocked["state"], "after": resolved["state"], "blocker_resolved": True},
+        "ai_calls": 0,
+        "unsafe_writes": 0,
+    }
+    (ROOT / "docs/AUTONOMOUS_OPERATION_SIMULATION_V1.json").write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/run_company_decision_session.py

@@ -0,0 +1,99 @@
+"""Prepare a single guided COMPANY-only decision session.
+
+Default mode is preview and never persists context. `--interactive --confirm`
+collects answers, validates them, and writes a reviewable artifact; importing
+that artifact remains a separate official operation.
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from central.app.ai.questionnaire import build_questionnaire, group_questions, render_json, validate_answers
+
+
+def _load_questions(path):
+    return json.loads(Path(path).read_text(encoding="utf-8"))["questions"]
+
+
+def _ipi_impact(root, database):
+    root = Path(root)
+    if database == "TESTESOFICIAIS":
+        coverage = json.loads((root / "docs/FISCAL_COVERAGE_FULL_V3.json").read_text(encoding="utf-8"))
+        ipi = coverage.get("ipi", {})
+        filled = sum(int(ipi.get(key, 0)) for key in ("numeric", "non_numeric", "ambiguous"))
+        return {"database": database, "products": coverage.get("total_products", 0), "currently_filled": filled, "would_revert": filled, "source": "FISCAL_COVERAGE_FULL_V3"}
+    path = root / f"docs/runs/multi_db/{database}.json"
+    if not path.exists():
+        return {"database": database, "products": None, "currently_filled": None, "would_revert": None, "source": "NOT_AVAILABLE"}
+    document = json.loads(path.read_text(encoding="utf-8"))
+    distribution = document.get("fiscal_field_distribution", {}).get("IPI", {})
+    values = distribution.get("top", [])
+    filled = sum(int(count) for value, count in values if value not in (None, ""))
+    return {"database": database, "products": document.get("product_count"), "currently_filled": filled, "would_revert": filled, "source": str(path.relative_to(root))}
+
+
+def build_session(root=".", questions_path="docs/LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json"):
+    root = Path(root)
+    rows = _load_questions(root / questions_path)
+    company_rows = [row for row in rows if str(row.get("SCOPE", "")).upper() == "COMPANY"]
+    databases = sorted({str(row.get("DATABASE") or "").strip() for row in company_rows if row.get("DATABASE")})
+    existing_ipi = {row.get("DATABASE") for row in company_rows if row.get("KEY") == "store_ipi_profile"}
+    for database in databases:
+        if database not in existing_ipi:
+            company_rows.append({
+                "QUESTION_ID": f"QIPI-{database}", "DATABASE": database, "SCOPE": "COMPANY", "GROUP": "", "KEY": "store_ipi_profile",
+                "VALID_OPTIONS": ["POPULATE_REFERENCE_RATE", "LEAVE_NOT_APPLICABLE"],
+                "QUESTION": "Guardar a aliquota TIPI como referencia no cadastro?", "PRODUCTS_AFFECTED": 0, "CELLS": 0,
+                "WHAT_IT_WILL_RESOLVE": "Define apenas o perfil de armazenamento; nao decide a aliquota automaticamente.",
+            })
+    questions = build_questionnaire(company_rows)
+    groups = group_questions(questions)
+    impact = {database: _ipi_impact(root, database) for database in sorted(set(databases) | {"TESTESOFICIAIS"})}
+    for group in groups:
+        if group["key"] == "store_ipi_profile":
+            group["ipi_impact"] = impact.get(group["database"], {})
+    return {
+        "artifact": "COMPANY_DECISION_SESSION_V1",
+        "mode": "REVIEW_ONLY",
+        "company_questions": len(questions),
+        "company_groups": len(groups),
+        "questions": groups,
+        "question_rows": questions,
+        "ipi_impact_by_database": impact,
+        "persisted": False,
+        "firebird_writes": 0,
+    }
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--questions", default="docs/LOCAL_FISCAL_CONTEXT_QUESTIONS_V2.json")
+    parser.add_argument("--interactive", action="store_true")
+    parser.add_argument("--confirm", action="store_true")
+    parser.add_argument("--output", default="docs/COMPANY_DECISION_SESSION_V1.json")
+    args = parser.parse_args(argv)
+    session = build_session(args.root, args.questions)
+    if args.interactive:
+        answers = {}
+        for question in session["questions"]:
+            print(json.dumps(question, ensure_ascii=False, indent=2))
+            value = input("RESPOSTA (ou CANCELAR): ").strip()
+            if value.upper() == "CANCELAR":
+                print("cancelado; nada foi persistido")
+                return 0
+            for question_id in question["question_ids"]:
+                answers[question_id] = value
+        result = validate_answers(session["question_rows"], answers)
+        session["answers"] = result
+        session["persisted"] = bool(args.confirm)
+    Path(args.output).write_text(json.dumps(session, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({"company_questions": session["company_questions"], "company_groups": session["company_groups"], "persisted": session["persisted"], "output": args.output}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fiscal/scripts/run_firebird_discovery.py

@@ -0,0 +1,661 @@
+"""Run the narrowly scoped, read-only Mission 00 Firebird probe."""
+
+from __future__ import annotations
+
+import argparse
+import ctypes
+import importlib.metadata
+import json
+import os
+import platform
+import re
+import struct
+import sys
+from pathlib import Path
+from typing import Any
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PROJECT_ROOT / "src"))
+
+from gti_discovery.firebird_connection import (
+    AUTHORIZED_DATABASE_PATH,
+    _FirebirdAdapter,
+    _ADAPTER_CREATION_TOKEN,
+    _create_firebird_adapter,
+    connect_authorized_read_only,
+    get_database_identity,
+    validate_authorized_database_path,
+    validate_authorized_database_identity,
+)
+from gti_discovery.collector import _safe_sample_rows, collect_metadata
+from gti_discovery.fingerprint import (
+    SCHEMA_CHANGED,
+    SCHEMA_SUPPORTED,
+    SCHEMA_UNKNOWN,
+    build_fingerprint,
+    classify_schema,
+)
+from gti_discovery.mapping import build_schema_mapping, identify_product_candidates
+from gti_discovery.provenance import (
+    ProvenanceError,
+    validate_fdb_provenance,
+    validate_imported_fdb_provenance,
+)
+
+
+DEFAULT_TARGET = AUTHORIZED_DATABASE_PATH
+CLIENT_LIBRARY = Path(r"C:\Program Files\Firebird\Firebird_2_5\bin\fbclient.dll")
+_BLOCKER_CATEGORIES = {
+    ValueError: "target_rejected",
+    ImportError: "driver_unavailable",
+    FileNotFoundError: "client_library_unavailable",
+    PermissionError: "connection_failed",
+    RuntimeError: "connection_failed",
+}
+
+
+class _FdbDriver:
+    version = "unknown"
+
+    def __init__(self, fdb_module: Any):
+        self._fdb = fdb_module
+        self.version = str(getattr(fdb_module, "__version__", "unknown"))
+        self._last_connection = None
+
+    def connect(self, **options):
+        if set(options) - {"database", "read_only", "client_library"}:
+            raise RuntimeError("unexpected connection settings")
+        if options.pop("read_only", None) is not True:
+            raise RuntimeError("read-only mode is required")
+        client_library = options.pop("client_library", None)
+        user = os.environ.get("FB_USER")
+        password = os.environ.get("FB_PASSWORD")
+        if not user or not password:
+            raise RuntimeError("Firebird credentials are unavailable in FB_USER/FB_PASSWORD")
+        isolation_level = _read_only_isolation_level(self._fdb)
+        raw = self._fdb.connect(
+            database=options["database"],
+            user=user,
+            password=password,
+            fb_library_name=client_library,
+            isolation_level=isolation_level,
+        )
+        self._last_connection = raw
+        observed = getattr(raw, "default_tpb", None)
+        if observed != isolation_level:
+            close = getattr(raw, "close", None)
+            if callable(close):
+                close()
+            raise RuntimeError("driver did not establish the fdb read-only TPB")
+        evidence = {
+            "accepted": True,
+            "driver_api": "fdb.Connection.default_tpb",
+            "configured_tpb": bytes(isolation_level),
+            "observed_default_tpb": bytes(observed),
+        }
+        return _create_firebird_adapter(raw, evidence, _ADAPTER_CREATION_TOKEN)
+
+    def facts(self) -> dict[str, Any]:
+        return {name: _fact(self._last_connection, name) for name in (
+            "engine_version", "database_sql_dialect", "ods_version",
+            "ods_minor_version", "charset", "page_size",
+        )}
+
+    def compatibility_evidence(self, client_version: str) -> dict[str, Any]:
+        isolation_level = _read_only_isolation_level(self._fdb)
+        return {
+            "fdb_version": self.version,
+            "client_version": client_version,
+            "firebird_version": ".".join(str(client_version).split(".")[:3]),
+            "read_only_isolation": _read_only_isolation_level(self._fdb) is not None,
+            "read_only_tpb": bytes(isolation_level),
+            "read_only_api": "fdb.Connection.default_tpb",
+        }
+
+
+def _read_only_isolation_level(fdb: Any) -> Any:
+    """Use fdb 2.0.4's actual read-only TPB constant (including its spelling)."""
+    value = getattr(fdb, "ISOLATION_LEVEL_READ_COMMITED_RO", None)
+    if isinstance(value, bytes) and value == b"\x03\x08\x06\x0f\x11":
+        return value
+    raise RuntimeError("fdb read-only isolation API is unavailable")
+
+
+def _fact(connection: Any, name: str) -> Any:
+    try:
+        value = getattr(connection, name)
+    except Exception:
+        return None
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return str(value)
+
+
+def _read_file_version(path: Path) -> str | None:
+    """Read Windows file-version metadata without loading the client DLL."""
+    if sys.platform != "win32":
+        return None
+    try:
+        version = ctypes.windll.version
+        size = version.GetFileVersionInfoSizeW(str(path), None)
+        if not size:
+            return None
+        buffer = ctypes.create_string_buffer(size)
+        if not version.GetFileVersionInfoW(str(path), 0, size, buffer):
+            return None
+        pointer = ctypes.c_void_p()
+        length = ctypes.c_uint()
+        if not version.VerQueryValueW(buffer, "\\", ctypes.byref(pointer), ctypes.byref(length)):
+            return None
+        class FixedFileInfo(ctypes.Structure):
+            _fields_ = [("signature", ctypes.c_uint32), ("struct_version", ctypes.c_uint32),
+                        ("file_version_ms", ctypes.c_uint32), ("file_version_ls", ctypes.c_uint32)]
+        info = ctypes.cast(pointer, ctypes.POINTER(FixedFileInfo)).contents
+        return ".".join((str(info.file_version_ms >> 16), str(info.file_version_ms & 0xffff),
+                         str(info.file_version_ls >> 16), str(info.file_version_ls & 0xffff)))
+    except Exception:
+        return None
+
+
+def _client_metadata(path: Path) -> dict[str, Any]:
+    exists = path.is_file()
+    return {"path": str(path), "exists": exists, "version": _read_file_version(path) if exists else None}
+
+
+def _read_client_architecture(path: Path) -> str:
+    """Read PE architecture metadata without loading or executing the DLL."""
+    try:
+        with path.open("rb") as handle:
+            if handle.read(2) != b"MZ":
+                return "UNKNOWN"
+            handle.seek(0x3C)
+            offset = struct.unpack("<I", handle.read(4))[0]
+            handle.seek(offset)
+            if handle.read(4) != b"PE\x00\x00":
+                return "UNKNOWN"
+            machine = struct.unpack("<H", handle.read(2))[0]
+    except (OSError, struct.error):
+        return "UNKNOWN"
+    return {0x014C: "x86", 0x8664: "x64", 0xAA64: "arm64"}.get(machine, "UNKNOWN")
+
+
+def _python_architecture() -> str:
+    return "x64" if struct.calcsize("P") == 8 else "x86" if struct.calcsize("P") == 4 else "UNKNOWN"
+
+
+def validate_firebird_runtime(*, fdb_module: Any = None) -> dict[str, Any]:
+    """Return deterministic dependency evidence; never infer unknown facts."""
+    try:
+        provenance = validate_fdb_provenance()
+    except ProvenanceError as error:
+        return {"status": "UNKNOWN", "blocker": "compatibility_unproven", "provenance": error.evidence}
+    client = _client_metadata(CLIENT_LIBRARY)
+    client = dict(client)
+    client["architecture"] = client.get("architecture", _read_client_architecture(CLIENT_LIBRARY))
+    distribution_version = None
+    try:
+        distribution_version = importlib.metadata.version("fdb")
+    except (importlib.metadata.PackageNotFoundError, ImportError):
+        pass
+    fdb_version = getattr(fdb_module, "__version__", distribution_version)
+    python_architecture = _python_architecture()
+    read_only_api = (
+        fdb_module is not None
+        and isinstance(getattr(fdb_module, "ISOLATION_LEVEL_READ_COMMITED_RO", None), bytes)
+        and getattr(fdb_module, "ISOLATION_LEVEL_READ_COMMITED_RO") == b"\x03\x08\x06\x0f\x11"
+    )
+    version_match = fdb_version == "2.0.4" and distribution_version == "2.0.4"
+    architecture_match = client["architecture"] in {"x86", "x64", "arm64"} and (
+        (python_architecture == "x64" and client["architecture"] == "x64")
+        or (python_architecture == "x86" and client["architecture"] == "x86")
+    )
+    valid = (
+        provenance.get("status") == "VALID"
+        and client["exists"] is True
+        and client["version"] == "2.5.9.27139"
+        and client["architecture"] != "UNKNOWN"
+        and architecture_match
+        and version_match
+        and fdb_module is not None
+        and read_only_api
+    )
+    compatibility = {
+        "status": "VALID" if valid else "UNKNOWN",
+        "python_client_architecture_match": architecture_match,
+        "fdb_client_version_match": version_match,
+        "read_only_api": read_only_api,
+    }
+    return {
+        "status": "VALID" if valid else "UNKNOWN",
+        "python_runtime": {"version": platform.python_version(), "architecture": python_architecture},
+        "fdb": {"version": fdb_version, "distribution_version": distribution_version},
+        "client": client,
+        "provenance": provenance,
+        "compatibility": compatibility,
+        **({} if valid else {"blocker": "compatibility_unproven"}),
+    }
+
+
+def _blocker_category(error: Exception) -> str:
+    if type(error).__name__ == "DatabaseError" and (
+        "-902" in str(error) or "user name and password are not defined" in str(error).lower()
+    ):
+        return "credentials_rejected"
+    if isinstance(error, ValueError) and "read-only" in str(error).lower():
+        return "read_only_unproven"
+    if isinstance(error, RuntimeError) and "credentials" in str(error).lower():
+        return "credentials_unavailable"
+    if isinstance(error, RuntimeError) and "compatib" in str(error).lower():
+        return "compatibility_unproven"
+    if isinstance(error, RuntimeError) and "provenance" in str(error).lower():
+        return "compatibility_unproven"
+    return next((category for error_type, category in _BLOCKER_CATEGORIES.items()
+                 if isinstance(error, error_type)), "unexpected_failure")
+
+
+def _firebird_259(version: Any) -> bool:
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)", str(version or ""))
+    return bool(match and tuple(int(item) for item in match.groups()) == (2, 5, 9))
+
+
+def _validate_runtime_compatibility(driver: Any) -> dict[str, Any]:
+    """Prove the installed 2.5.9 client and usable driver before connect."""
+    client = _client_metadata(CLIENT_LIBRARY)
+    if not client["exists"] or not _firebird_259(client["version"]):
+        raise RuntimeError("Firebird 2.5.9 client compatibility is unproven")
+    if type(driver) is not _FdbDriver:
+        raise RuntimeError("Firebird driver/client compatibility is unproven")
+    try:
+        import fdb as installed_fdb
+        installed_version = importlib.metadata.version("fdb")
+    except (ImportError, importlib.metadata.PackageNotFoundError) as error:
+        raise RuntimeError("Firebird driver/client compatibility is unproven") from error
+    if (
+        driver._fdb is not installed_fdb
+        or installed_version != "2.0.4"
+        or getattr(installed_fdb, "__version__", None) != "2.0.4"
+        or _read_only_isolation_level(installed_fdb) != b"\x03\x08\x06\x0f\x11"
+    ):
+        raise RuntimeError("Firebird driver/client compatibility is unproven")
+    return client
+
+
+def _validate_preimport_compatibility() -> dict[str, Any]:
+    provenance = validate_fdb_provenance()
+    client = _client_metadata(CLIENT_LIBRARY)
+    client = dict(client)
+    client["architecture"] = client.get("architecture", _read_client_architecture(CLIENT_LIBRARY))
+    try:
+        fdb_version = importlib.metadata.version("fdb")
+    except importlib.metadata.PackageNotFoundError as error:
+        raise RuntimeError("fdb 2.0.4 compatibility is unproven") from error
+    if (
+        not client["exists"]
+        or not _firebird_259(client["version"])
+        or client["architecture"] == "UNKNOWN"
+        or client["architecture"] != _python_architecture()
+        or fdb_version != "2.0.4"
+    ):
+        raise RuntimeError("Firebird 2.5.9/fdb 2.0.4 compatibility is unproven")
+    if not _preimport_read_only_api_proven():
+        raise RuntimeError("Firebird read-only isolation API compatibility is unproven")
+    return {"client": client, "provenance": provenance}
+
+
+def _preimport_read_only_api_proven() -> bool:
+    """Prove the pinned driver's read-only API from installed source, without import."""
+    try:
+        spec = __import__("importlib.util", fromlist=["find_spec"]).find_spec("fdb")
+        locations = list(getattr(spec, "submodule_search_locations", ()) or ())
+        if not locations:
+            return False
+        package = Path(locations[0])
+        init_source = (package / "__init__.py").read_text(encoding="utf-8")
+        core_source = (package / "fbcore.py").read_text(encoding="utf-8")
+    except (OSError, UnicodeError, ImportError, AttributeError, TypeError):
+        return False
+    return (
+        "ISOLATION_LEVEL_READ_COMMITED_RO" in init_source
+        and "ISOLATION_LEVEL_READ_COMMITED_RO = bs([" in core_source
+        and all(token in core_source for token in (
+            "isc_tpb_version3", "isc_tpb_read", "isc_tpb_wait",
+            "isc_tpb_read_committed", "isc_tpb_rec_version",
+        ))
+    )
+
+
+def _security_gate(path: os.PathLike[str] | str, driver: Any) -> dict[str, Any]:
+    validate_authorized_database_path(path)
+    if not os.environ.get("FB_USER") or not os.environ.get("FB_PASSWORD"):
+        raise RuntimeError("Firebird credentials are unavailable in FB_USER/FB_PASSWORD")
+    evidence = validate_firebird_runtime(fdb_module=getattr(driver, "_fdb", None))
+    if evidence["status"] != "VALID":
+        raise RuntimeError("Firebird driver/client compatibility is unproven")
+    return {"client": evidence["client"], "compatibility_evidence": evidence}
+
+
+_SAMPLE_DENYLIST = (
+    "CUSTOMER", "CLIENT", "EMAIL", "PHONE", "MOBILE", "CONTACT", "ADDRESS",
+    "PRICE", "COST", "AMOUNT", "TOTAL", "TAX", "CRED", "PASSWORD",
+    "SECRET", "TOKEN", "BLOB", "SOURCE", "DEFAULT", "SALARY", "MARGIN",
+    "DISCOUNT", "PROFIT", "IMAGE", "PHOTO", "FILE", "PATH", "URL",
+)
+_SAMPLE_ALLOWLIST = (
+    "ID", "KEY", "CODE", "CODIGO", "SKU", "ITEM", "PRODUCT", "DESCRIPTION",
+    "DESCRICAO", "NAME", "NOME", "BARCODE", "EAN", "GTIN", "REFERENCE",
+    "REFERENCIA", "REF", "UNIT", "UNIDADE", "CATEGORY", "GROUP", "GRUPO",
+    "BRAND", "MARCA", "PRODUTO", "ESTOQUE", "STATUS", "ACTIVE", "ATIVO",
+)
+
+
+def _permitted_sample_plan(metadata: dict[str, Any]) -> list[tuple[str, list[str]]]:
+    fields_by_relation: dict[str, list[dict[str, Any]]] = {}
+    for field in metadata.get("fields", []):
+        if not isinstance(field, dict):
+            continue
+        relation = str(field.get("RELATION_NAME", "")).strip()
+        if relation:
+            fields_by_relation.setdefault(relation.upper(), []).append(field)
+    candidates = identify_product_candidates(metadata, {})
+    plan = []
+    for candidate in candidates:
+        relation = str(candidate.get("relation", "")).strip()
+        if not relation or candidate.get("classification") == "UNKNOWN":
+            continue
+        columns = []
+        for field in fields_by_relation.get(relation.upper(), []):
+            name = str(field.get("FIELD_NAME", "")).strip()
+            type_name = str(field.get("TYPE_NAME", field.get("FIELD_TYPE", ""))).upper()
+            upper_name = name.upper()
+            if not name or any(word in upper_name for word in _SAMPLE_DENYLIST):
+                continue
+            if "BLOB" in type_name or not any(word in upper_name for word in _SAMPLE_ALLOWLIST):
+                continue
+            columns.append(name)
+        if columns:
+            plan.append((relation, columns[:8]))
+    return plan
+
+
+def _collect_samples(reader: Any, metadata: dict[str, Any]) -> dict[str, list[dict[str, Any]]]:
+    samples = {}
+    plan = _permitted_sample_plan(metadata)
+    if not isinstance(plan, list) or any(
+        not isinstance(item, tuple)
+        or len(item) != 2
+        or not isinstance(item[0], str)
+        or not isinstance(item[1], list)
+        or not item[1]
+        or any(
+            not isinstance(column, str)
+            or any(word in column.upper() for word in _SAMPLE_DENYLIST)
+            or not any(word in column.upper() for word in _SAMPLE_ALLOWLIST)
+            for column in item[1]
+        )
+        for item in plan
+    ):
+        raise RuntimeError("sample plan is not permitted")
+    for relation, columns in plan:
+        rows = reader.sample_relation_rows(relation, columns, 5)
+        if not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows):
+            raise RuntimeError("sample evidence is malformed")
+        samples[relation] = _safe_sample_rows(rows)
+    return samples
+
+
+def _blocked(
+    blocker: str,
+    *,
+    connection_attempts: int = 0,
+    other_databases_accessed: int | str = 0,
+) -> dict[str, Any]:
+    return {
+        "status": "MISSION_00_BLOCKED",
+        "blocker": blocker,
+        "application_writes": 0,
+        "other_databases_accessed": other_databases_accessed,
+        "connection_attempts": connection_attempts,
+    }
+
+
+def _valid_metadata(metadata: Any) -> bool:
+    if not isinstance(metadata, dict):
+        return False
+    if not all(isinstance(metadata.get(name), list) for name in ("relations", "fields", "errors", "unavailable")):
+        return False
+    return (
+        all(isinstance(row, dict) for name in ("relations", "fields", "errors") for row in metadata[name])
+        and all(isinstance(name, str) and bool(name) for name in metadata["unavailable"])
+    )
+
+
+def _valid_mapping(mapping: Any) -> bool:
+    required = {"product", "fields", "fiscal", "stock", "media", "incremental", "triggers"}
+    if type(mapping) is not dict or set(mapping) != required:
+        return False
+    allowed = {"CONFIRMED", "INFERRED", "UNKNOWN"}
+
+    def strings(value: Any) -> bool:
+        return type(value) is list and all(type(item) is str and bool(item) for item in value)
+
+    def classified(value: Any, keys: set[str]) -> bool:
+        return type(value) is dict and set(value) == keys and value["classification"] in allowed
+
+    def field_record(value: Any) -> bool:
+        if type(value) is not dict or not {"classification", "sample_present", "type"} <= set(value):
+            return False
+        if set(value) - {"classification", "sample_present", "type", "subtype", "value"}:
+            return False
+        return value["classification"] in allowed and type(value["sample_present"]) is bool and type(value["type"]) is str and bool(value["type"]) and all(
+            type(value[key]) in (str, int, float, bool) for key in ("subtype", "value") if key in value
+        )
+
+    def field_map(value: Any) -> bool:
+        return type(value) is dict and all(type(key) is str and bool(key) and field_record(item) for key, item in value.items())
+
+    def relation_record(value: Any) -> bool:
+        if type(value) is not dict or not {"classification", "fields", "relationships"} <= set(value):
+            return False
+        if set(value) - {"classification", "fields", "relationships", "evidence"}:
+            return False
+        relationships = value["relationships"]
+        return value["classification"] in allowed and field_map(value["fields"]) and type(relationships) is list and all(
+            type(item) is dict and set(item) == {"child_relation", "child_field", "referenced_relation", "referenced_field"}
+            and all(type(item[key]) is str and bool(item[key]) for key in item)
+            for item in relationships
+        ) and ("evidence" not in value or type(value["evidence"]) is str)
+
+    def relation_map(value: Any) -> bool:
+        return type(value) is dict and all(type(key) is str and bool(key) and relation_record(item) for key, item in value.items())
+
+    product = mapping["product"]
+    product_keys = {"classification", "relation", "evidence", "candidates"}
+    candidate_keys = {"classification", "relation", "evidence"}
+    evidence_keys = {"primary_key", "field_count", "semantic_fields", "sample_fields", "semantic_sample_fields", "approximate_count"}
+    if not classified(product, product_keys) or (product["relation"] is not None and (type(product["relation"]) is not str or not product["relation"])) or type(product["evidence"]) is not dict or set(product["evidence"]) - evidence_keys:
+        return False
+    candidates = product.get("candidates")
+    if not isinstance(candidates, list) or not all(
+        classified(item, candidate_keys) and type(item["relation"]) is str and bool(item["relation"])
+        and type(item["evidence"]) is dict and set(item["evidence"]) - evidence_keys == set()
+        and strings(item["evidence"].get("primary_key"))
+        and type(item["evidence"].get("field_count")) is int
+        and strings(item["evidence"].get("semantic_fields")) for item in candidates
+    ):
+        return False
+    for evidence in (product["evidence"], *(item["evidence"] for item in candidates)):
+        if not evidence:
+            continue
+        if not strings(evidence.get("primary_key")) or type(evidence.get("field_count")) is not int or evidence["field_count"] < 0 or not strings(evidence.get("semantic_fields")):
+            return False
+        if "sample_fields" in evidence and not strings(evidence["sample_fields"]):
+            return False
+        if "semantic_sample_fields" in evidence and not strings(evidence["semantic_sample_fields"]):
+            return False
+        if "approximate_count" in evidence and type(evidence["approximate_count"]) not in (str, int, float, bool, type(None)):
+            return False
+    if not field_map(mapping["fields"]):
+        return False
+    for section in ("fiscal", "media"):
+        value = mapping[section]
+        if not classified(value, {"classification", "fields", "relations"}) or not field_map(value["fields"]) or not relation_map(value["relations"]):
+            return False
+    if not classified(mapping["stock"], {"classification", "relations"}) or not relation_map(mapping["stock"]["relations"]):
+        return False
+    incremental = mapping["incremental"]
+    evidence = incremental.get("evidence")
+    if not classified(incremental, {"classification", "evidence"}) or type(evidence) is not dict or set(evidence) != {"timestamps", "triggers", "generators"}:
+        return False
+    if not strings(evidence["timestamps"]) or type(evidence["triggers"]) is not int or evidence["triggers"] < 0 or type(evidence["generators"]) is not int or evidence["generators"] < 0:
+        return False
+    triggers = mapping["triggers"]
+    return type(triggers) is list and all(
+        classified(trigger, {"classification", "relation", "trigger", "timing", "event", "trigger_type", "dependencies", "source"})
+        and all(type(trigger[key]) is str and bool(trigger[key]) for key in ("relation", "trigger", "timing", "event", "source"))
+        and type(trigger["trigger_type"]) in (str, int) and bool(str(trigger["trigger_type"]))
+        and strings(trigger.get("dependencies"))
+        for trigger in triggers
+    )
+
+
+def _valid_fingerprint(value: Any) -> bool:
+    return isinstance(value, str) and bool(re.fullmatch(r"[0-9a-f]{64}", value))
+
+
+def _public_compatibility(evidence: Any) -> dict[str, str]:
+    """Expose compatibility categories only; never serialize internal evidence."""
+    if not isinstance(evidence, dict):
+        return {"status": "UNKNOWN"}
+    return {
+        "status": evidence.get("status", "UNKNOWN") if evidence.get("status") in {"VALID", "UNKNOWN"} else "UNKNOWN",
+        "architecture": "MATCH" if evidence.get("compatibility", {}).get("python_client_architecture_match") is True else "UNKNOWN",
+        "fdb_client": "MATCH" if evidence.get("compatibility", {}).get("fdb_client_version_match") is True else "UNKNOWN",
+        "read_only_api": "PROVEN" if evidence.get("compatibility", {}).get("read_only_api") is True else "UNKNOWN",
+    }
+
+
+def _public_metadata(metadata: dict[str, Any]) -> dict[str, Any]:
+    """Remove database identity rows, which may contain an absolute FDB path."""
+    return {key: value for key, value in metadata.items() if key != "database"}
+
+
+def run_discovery(path: os.PathLike[str] | str, *, driver: Any) -> dict[str, Any]:
+    """Run the gated, structured, sanitized discovery workflow."""
+    try:
+        security = _security_gate(path, driver)
+        client = security.get("client", security)
+    except RuntimeError as error:
+        return _blocked(_blocker_category(error))
+    try:
+        connection = connect_authorized_read_only(
+            path, driver, client_library=str(CLIENT_LIBRARY)
+        )
+    except Exception as error:
+        return _blocked(_blocker_category(error), connection_attempts=1)
+    try:
+        try:
+            database_name = get_database_identity(connection)
+            validate_authorized_database_identity(database_name, path)
+        except Exception:
+            return _blocked(
+                "identity_mismatch",
+                connection_attempts=1,
+                other_databases_accessed="UNKNOWN",
+            )
+        try:
+            facts = driver.facts() if callable(getattr(driver, "facts", None)) else {}
+            metadata = collect_metadata(connection)
+            if not _valid_metadata(metadata):
+                return _blocked("discovery_invalid", connection_attempts=1)
+            samples = _collect_samples(connection, metadata)
+            mapping = build_schema_mapping(metadata, samples)
+            if not _valid_mapping(mapping):
+                return _blocked("discovery_invalid", connection_attempts=1)
+            unavailable = set(metadata.get("unavailable", []))
+            optional_catalog_gaps = {"events", "packages", "procedure_parameters"}
+            blocking_errors = [
+                error for error in metadata.get("errors", [])
+                if not (
+                    error.get("kind") == "optional_unsupported"
+                    or error.get("query") == "monitoring"
+                )
+            ]
+            complete = (
+                not blocking_errors
+                and unavailable <= optional_catalog_gaps
+                and (not metadata.get("incomplete") or bool(unavailable) and unavailable <= optional_catalog_gaps)
+                and bool(metadata.get("relations"))
+                and bool(samples)
+            )
+            fingerprint = None
+            classification = SCHEMA_UNKNOWN
+            if complete:
+                evidence = {"metadata": metadata, "samples": samples, "mapping": mapping}
+                fingerprint = build_fingerprint(evidence)
+                if not _valid_fingerprint(fingerprint):
+                    return _blocked("discovery_invalid", connection_attempts=1)
+                expected = getattr(driver, "expected_fingerprints", ())
+                classification = classify_schema(
+                    metadata,
+                    expected,
+                    mapping_ambiguous=mapping.get("product", {}).get("classification") == "UNKNOWN",
+                )
+                if classification not in {SCHEMA_SUPPORTED, SCHEMA_CHANGED, SCHEMA_UNKNOWN}:
+                    return _blocked("discovery_invalid", connection_attempts=1)
+            return {
+                "status": "CONNECTED" if complete else SCHEMA_UNKNOWN,
+                "driver_version": str(getattr(driver, "version", "unknown")),
+                "architecture": platform.architecture()[0],
+                "engine_version": facts.get("engine_version"),
+                "dialect": facts.get("database_sql_dialect"),
+                "ods": {
+                    "major": facts.get("ods_version"),
+                    "minor": facts.get("ods_minor_version"),
+                },
+                "charset": facts.get("charset"),
+                "page_size": facts.get("page_size"),
+                "metadata": _public_metadata(metadata),
+                "samples": samples,
+                "schema_mapping": mapping,
+                "fingerprint": fingerprint,
+                "schema_classification": classification,
+                "compatibility": _public_compatibility(security.get("compatibility_evidence")),
+                "application_writes": 0,
+                "other_databases_accessed": 0,
+                "connection_attempts": 1,
+            }
+        except Exception:
+            return _blocked("discovery_failed", connection_attempts=1)
+    finally:
+        connection.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.parse_args(argv)
+    try:
+        if not os.environ.get("FB_USER") or not os.environ.get("FB_PASSWORD"):
+            raise RuntimeError("credentials unavailable")
+        compatibility = _validate_preimport_compatibility()
+        import fdb
+
+        provenance = validate_imported_fdb_provenance(fdb)
+        runtime_compatibility = validate_firebird_runtime(fdb_module=fdb)
+        if runtime_compatibility["status"] != "VALID":
+            raise RuntimeError("Firebird driver/client compatibility is unproven")
+        result = run_discovery(DEFAULT_TARGET, driver=_FdbDriver(fdb))
+        result["compatibility"] = _public_compatibility(runtime_compatibility)
+    except Exception as error:
+        result = {
+            "status": "MISSION_00_BLOCKED",
+            "blocker": _blocker_category(error),
+            "application_writes": 0,
+            "other_databases_accessed": 0,
+            "connection_attempts": 0,
+        }
+    print(json.dumps(result, ensure_ascii=True, sort_keys=True))
+    return 0 if result["status"] == "CONNECTED" else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fiscal/scripts/run_first_write.py

@@ -0,0 +1,113 @@
+"""Run the MVP's first real, guarded Firebird write (test DB only) and verify it.
+
+Loads a single write_eligible IPI proposal from a DRY_RUN_PLAN artifact,
+re-reads the live row to check for drift, performs the guarded UPDATE via
+firebird_write_executor, verifies persistence, and writes an audit log with
+no secrets. Only ever targets TESTESOFICIAIS.FDB (enforced by the executor).
+"""
+import argparse
+import importlib.util
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_executor():
+    spec = importlib.util.spec_from_file_location("firebird_write_executor", ROOT / "scripts" / "firebird_write_executor.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_dotenv(path: Path) -> None:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ[key.strip()] = value.strip()
+
+
+def pick_proposal(plan: dict, product_code: str | None) -> dict:
+    eligible = [p for p in plan["field_proposals"] if p["field"] == "IPI" and p["write_eligible"]]
+    if not eligible:
+        raise SystemExit("no write_eligible IPI proposal available")
+    if product_code:
+        chosen = next((p for p in eligible if p["product_code"] == product_code), None)
+        if chosen is None:
+            raise SystemExit(f"product {product_code} is not write_eligible")
+        return chosen
+    return eligible[0]
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--plan", default=str(ROOT / "docs" / "DRY_RUN_PLAN_V3.json"))
+    parser.add_argument("--product-code", default=None)
+    parser.add_argument("--audit-log", default=str(ROOT / "docs" / "runs" / "first_write_audit.json"))
+    args = parser.parse_args()
+
+    load_dotenv(ROOT / ".env")
+    executor = load_executor()
+
+    plan = json.loads(Path(args.plan).read_text(encoding="utf-8"))
+    proposal = pick_proposal(plan, args.product_code)
+
+    import fdb
+    database_path = os.environ["FIREBIRD_DATABASE_PATH"]
+    executor.assert_authorized_write_path(database_path)
+
+    connection = fdb.connect(
+        database=database_path,
+        user=os.environ["FB_USER"],
+        password=os.environ["FB_PASSWORD"],
+        fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+    )
+    try:
+        cursor = connection.cursor()
+        cursor.execute(
+            "SELECT CODIGO, CLASSIFICACAO_FISCAL, IPI FROM C000025 WHERE CODIGO = ?",
+            (proposal["product_code"],),
+        )
+        row = cursor.fetchone()
+        if row is None:
+            raise SystemExit(f"product {proposal['product_code']} not found")
+        codigo, ncm, live_ipi = row
+        if live_ipi != proposal["current_value"]:
+            raise SystemExit(
+                f"drift before write: plan expected {proposal['current_value']!r}, "
+                f"live is {live_ipi!r} — refusing to write, choose another eligible product"
+            )
+        cursor.close()
+
+        now = datetime.now(timezone.utc).isoformat()
+        record = executor.execute_guarded_update(
+            connection,
+            database_path=database_path,
+            proposal=proposal,
+            now=now,
+        )
+        audit = {
+            **record.as_dict(),
+            "ncm": ncm,
+            "database": str(executor.AUTHORIZED_WRITE_DATABASE_PATH),
+            "table": "C000025",
+        }
+        audit_path = Path(args.audit_log)
+        audit_path.parent.mkdir(parents=True, exist_ok=True)
+        existing = json.loads(audit_path.read_text(encoding="utf-8")) if audit_path.exists() else []
+        existing.append(audit)
+        audit_path.write_text(json.dumps(existing, indent=2, ensure_ascii=False), encoding="utf-8")
+
+        print(json.dumps(audit, indent=2, ensure_ascii=False))
+    finally:
+        connection.close()
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/run_fiscal_decision_v1.py

@@ -0,0 +1,221 @@
+"""Fiscal Decision Engine V1 runner.
+
+Reads all C000025 products (read-only), classifies via the Hub, applies
+central.app.fiscal_decision per domain, writes the matrix/coverage/priorities
+artifacts, and with --apply executes ONLY AUTO_APPLY_SAFE proposals against
+TESTESOFICIAIS.FDB (path guard enforced by firebird_write_executor), followed
+by an independent re-read.
+"""
+import argparse
+import importlib.util
+import json
+import os
+import sys
+import urllib.request
+from collections import Counter, defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+
+from central.app.fiscal_decision import DECISION_ENGINE_VERSION, ERP_FIELD_MAP, NATURE, decide_product  # noqa: E402
+from gti_fiscal_agent.firebird_reader import _connect, parse_company_context  # noqa: E402
+
+DOMAIN_FIELDS = ("NCM", "IPI", "EX_TIPI", "CEST", "MVA", "CFOP", "CSOSN", "CST_ICMS", "ORIGEM", "PIS_CST", "COFINS_CST",
+                 "PIS_COFINS_RATE", "FCP", "RTC_CCLASSTRIB", "RTC_CBS_RATE", "RTC_CCREDPRES")
+NEXT_ACTION = {
+    "NCM": "Review LEGACY/INVALID NCMs manually (no unambiguous successor); never auto-change.",
+    "IPI": "Keep auto-apply; NON_NUMERIC/blank TIPI rows need a business decision on how ERP represents NT.",
+    "EX_TIPI": "Propose only when a single concrete EX applies; needs product-description evidence.",
+    "CEST": "Improve description evidence per candidate group (do not lower threshold); manual review queue for candidates.",
+    "MVA": "Confirm CEST first; then identify the ERP destination field for MVA (none proven).",
+    "CFOP": "Requires operation context (direction, destination UF, ST, purpose) — capture it at document level.",
+    "CSOSN": "Requires sale scenario/ST retention context; consider per-product default review for ST-annex NCMs.",
+    "CST_ICMS": "Not used under CRT=1; only relevant if the client changes regime.",
+    "ORIGEM": "Obtain objective product origin (supplier/import flag) before any write; ERP CST prefix is not proof.",
+    "PIS_CST": "Needs regime+incidence rule table (deferred 4.3.x) — measure need from client data first.",
+    "COFINS_CST": "Same as PIS_CST.",
+    "PIS_COFINS_RATE": "Needs source tables (deferred); never assume 0%.",
+    "FCP": "Needs destination UF + operation + BA FCP item list per NCM.",
+    "RTC_CCLASSTRIB": "Needs official NCM->annex/cClassTrib mapping (LC 214 annexes) — not in acquired datasets.",
+    "RTC_CBS_RATE": "Blocked by cClassTrib; apply 0.009 only where the official rule applies.",
+    "RTC_CCREDPRES": "Official conditions not derivable from product data.",
+}
+
+
+def load_dotenv(path):
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            k, _, v = line.partition("=")
+            os.environ.setdefault(k.strip(), v.strip())
+
+
+def http(url, token, payload=None):
+    data = json.dumps(payload, ensure_ascii=True).encode() if payload is not None else None
+    req = urllib.request.Request(url, data=data, headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}, method="POST" if payload is not None else "GET")
+    with urllib.request.urlopen(req, timeout=600) as r:
+        return json.load(r)
+
+
+def read_all(env):
+    conn = _connect(env)
+    try:
+        cur = conn.cursor()
+        cur.execute("""SELECT CODIGO,PRODUTO,CLASSIFICACAO_FISCAL,CFOP,CST,CSOSN,CEST,IPI,EX_TIPI,ORIGEM,COD_SAIDA_PIS,COD_SAIDA_COFINS,ALIQ_PIS FROM C000025 ORDER BY CODIGO""")
+        names = [c[0].strip() for c in cur.description]
+        rows = [dict(zip(names, r)) for r in cur.fetchall()]
+        cur.execute("SELECT UF, CRT FROM C000004")
+        return rows, parse_company_context(cur.fetchall())
+    finally:
+        conn.close()
+
+
+def build_refs(hub, token, products, company_uf):
+    refs = {}
+    for key, dom in (("csosn", "CSOSN"), ("cst_icms", "CST_ICMS"), ("cst_pis", "CST_PIS"), ("cst_cofins", "CST_COFINS"), ("origem", "ORIGEM_MERCADORIA")):
+        refs[key] = set(http(f"{hub}/v1/reference/fiscal_codes/{dom}", token)["codes"])
+    valid = set()
+    for code in {str(p["CFOP"]).strip() for p in products if p.get("CFOP")}:
+        if http(f"{hub}/v1/reference/cfop/{code}", token)["found"]:
+            valid.add(code)
+    refs["cfop_valid"] = valid
+    refs["fcp_uf"] = {}
+    r = http(f"{hub}/v1/reference/fcp/{company_uf}", token)
+    if r["found"]:
+        refs["fcp_uf"][company_uf] = r
+    refs["cbs_rate_2026"] = http(f"{hub}/v1/reference/rtc_cbs_rate/2026", token).get("rate")
+    status = http(f"{hub}/v1/datasets/status", token)
+    refs["cclasstrib_count"] = sum(d["record_count"] for d in status if d["kind"] == "RTC_CCLASSTRIB" and d["status"] == "ACTIVE")
+    return refs
+
+
+def load_executor():
+    spec = importlib.util.spec_from_file_location("firebird_write_executor", ROOT / "scripts" / "firebird_write_executor.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def summarize(matrix):
+    cov = {}
+    for dom in DOMAIN_FIELDS:
+        rows = [m["fields"][dom] for m in matrix]
+        c = Counter(r["status"] for r in rows)
+        act = Counter(r["action_class"] for r in rows)
+        cov[dom] = {
+            "nature": NATURE[dom],
+            "DATA_AVAILABLE": sum(r["data_available"] for r in rows),
+            "MATCH_FOUND": sum(r["match_found"] for r in rows),
+            "RULE_RESOLVED": c["RULE_RESOLVED"], "RULE_CANDIDATE": c["RULE_CANDIDATE"], "RULE_UNRESOLVED": c["RULE_UNRESOLVED"],
+            "OPERATION_CONTEXT_REQUIRED": c["OPERATION_CONTEXT_REQUIRED"],
+            "CHANGE_REQUIRED": sum(1 for r in rows if r["write_eligible"]),
+            "action_class": dict(act),
+            "reason_codes": dict(Counter(r["reason_code"] for r in rows).most_common(6)),
+        }
+    return cov
+
+
+def priorities_md(cov):
+    def key(d):
+        c = cov[d]
+        return (-c["action_class"].get("AUTO_APPLY_SAFE", 0), -c["CHANGE_REQUIRED"], -c["RULE_RESOLVED"], -c["RULE_CANDIDATE"], d)
+    lines = ["# NEXT_FISCAL_AUTOMATION_PRIORITIES_V1", "",
+             "Generated by `scripts/run_fiscal_decision_v1.py` from `docs/FISCAL_DECISION_COVERAGE_V1.json` (521 products).",
+             "Ordering is mechanical: AUTO_APPLY_SAFE desc, CHANGE_REQUIRED desc, RESOLVED_PRODUCTS desc, candidates desc.", "",
+             "| FIELD | RESOLVED_PRODUCTS | CHANGE_REQUIRED | AUTO_APPLY_SAFE | CANDIDATES | OP_CONTEXT_REQUIRED | BLOCKER | NEXT_ACTION |", "|---|---|---|---|---|---|---|---|"]
+    for d in sorted(cov, key=key):
+        c = cov[d]
+        blocker = next(iter(c["reason_codes"]), "-")
+        lines.append(f"| {d} | {c['RULE_RESOLVED']} | {c['CHANGE_REQUIRED']} | {c['action_class'].get('AUTO_APPLY_SAFE', 0)} | {c['RULE_CANDIDATE']} | {c['OPERATION_CONTEXT_REQUIRED']} | {blocker} | {NEXT_ACTION[d]} |")
+    return "\n".join(lines) + "\n"
+
+
+def apply_writes(matrix, products_by_code, executor):
+    """Only AUTO_APPLY_SAFE + write_eligible; executor enforces path/allowlist/compare-before-write."""
+    import fdb
+    database_path = os.environ["FIREBIRD_DATABASE_PATH"]
+    executor.assert_authorized_write_path(database_path)
+    per_field = defaultdict(lambda: Counter())
+    audit = []
+    conn = fdb.connect(database=database_path, user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"))
+    try:
+        for m in matrix:
+            for dom, rec in m["fields"].items():
+                if not (rec["write_eligible"] and rec["action_class"] == "AUTO_APPLY_SAFE"):
+                    continue
+                field = {"IPI": "IPI", "EX_TIPI": "EX_TIPI", "CEST": "CEST"}[dom]
+                per_field[field]["ATTEMPTED"] += 1
+                proposal = {"product_code": m["CODIGO"], "field": field, "current_value": rec["current_value"], "proposed_value": rec["proposed_value"],
+                            "status": "CHANGE_REQUIRED", "write_eligible": True, "source_dataset": rec["provenance"]["dataset"], "source_version": rec["provenance"]["version"]}
+                try:
+                    r = executor.execute_guarded_update(conn, database_path=database_path, proposal=proposal, now=datetime.now(timezone.utc).isoformat())
+                    per_field[field]["SUCCEEDED"] += 1
+                    audit.append({**r.as_dict(), "outcome": "SUCCEEDED"})
+                except executor.WriteRefused as e:
+                    per_field[field]["FAILED"] += 1
+                    audit.append({"product_code": m["CODIGO"], "field": field, "proposed_value": rec["proposed_value"], "outcome": "FAILED", "error": str(e)})
+    finally:
+        conn.close()
+    ro = _connect(os.environ)
+    try:
+        cur = ro.cursor()
+        for a in audit:
+            if a["outcome"] != "SUCCEEDED":
+                continue
+            cur.execute(f"SELECT {a['field']} FROM C000025 WHERE CODIGO = ?", (a["product_code"],))
+            live = cur.fetchone()[0]
+            if str(live).strip() == str(a["proposed_value"]).strip():
+                per_field[a["field"]]["POST_WRITE_VERIFIED"] += 1
+    finally:
+        ro.close()
+    return {f: dict(c) for f, c in per_field.items()}, audit
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--token", required=True)
+    ap.add_argument("--hub-url", default="http://localhost:8000")
+    ap.add_argument("--apply", action="store_true")
+    args = ap.parse_args()
+    load_dotenv(ROOT / ".env")
+
+    products, company = read_all(os.environ)
+    refs = build_refs(args.hub_url, args.token, products, company['uf'])
+    decisions = []
+    for i in range(0, len(products), 100):
+        chunk = products[i:i + 100]
+        decisions += http(f"{args.hub_url}/v1/classify/batch", args.token, {"products": [{"current_ncm": p["CLASSIFICACAO_FISCAL"], "description": p["PRODUTO"] or ""} for p in chunk]})["results"]
+
+    matrix = []
+    for p, d in zip(products, decisions):
+        matrix.append({"CODIGO": p["CODIGO"], "DESCRIPTION": p["PRODUTO"], "NCM": p["CLASSIFICACAO_FISCAL"], "fields": decide_product(p, d, company, refs)})
+
+    cov = summarize(matrix)
+    totals = Counter()
+    for m in matrix:
+        for rec in m["fields"].values():
+            totals[rec["action_class"]] += 1
+    (ROOT / "docs" / "FISCAL_DECISION_MATRIX_V1.json").write_text(json.dumps({
+        "artifact": "FISCAL_DECISION_MATRIX_V1", "engine": DECISION_ENGINE_VERSION, "company_context": company,
+        "total_products": len(matrix), "erp_field_map": ERP_FIELD_MAP, "products": matrix}, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    coverage = {"artifact": "FISCAL_DECISION_COVERAGE_V1", "engine": DECISION_ENGINE_VERSION, "total_products": len(matrix), "company_context": company,
+                "erp_fields_mapped": sum(1 for f in ERP_FIELD_MAP if f["MAPPING"] == "CONFIRMED"),
+                "erp_fields_unconfirmed": [f["ERP_FIELD"] for f in ERP_FIELD_MAP if f["MAPPING"] != "CONFIRMED"],
+                "action_class_totals": dict(totals), "domains": cov, "reference_cbs_rate_2026": refs["cbs_rate_2026"]}
+    write_result = None
+    if args.apply:
+        write_result, audit = apply_writes(matrix, {p["CODIGO"]: p for p in products}, load_executor())
+        coverage["writes"] = write_result
+        (ROOT / "docs" / "runs").mkdir(exist_ok=True)
+        (ROOT / "docs" / "runs" / "fiscal_decision_v1_write_audit.json").write_text(json.dumps(audit, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    (ROOT / "docs" / "FISCAL_DECISION_COVERAGE_V1.json").write_text(json.dumps(coverage, ensure_ascii=False, indent=1), encoding="utf-8")
+    (ROOT / "docs" / "NEXT_FISCAL_AUTOMATION_PRIORITIES_V1.md").write_text(priorities_md(cov), encoding="utf-8")
+    print(json.dumps({"action_class_totals": dict(totals), "writes": write_result,
+                      "domains": {d: {k: v for k, v in c.items() if k in ("RULE_RESOLVED", "RULE_CANDIDATE", "RULE_UNRESOLVED", "OPERATION_CONTEXT_REQUIRED", "CHANGE_REQUIRED", "MATCH_FOUND")} for d, c in cov.items()}}, indent=1))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/run_full_database_batch.py

@@ -0,0 +1,262 @@
+"""MVP first real batch: classify all of C000025, dry-run the IPI plan, then
+execute every write_eligible IPI proposal against TESTESOFICIAIS.FDB only.
+
+Phases:
+  1. Read all products from C000025 (read-only).
+  2. Classify each via the running fiscal-hub /v1/classify/batch.
+  3. Build field proposals (dry-run) with central.app.dry_run_planner.
+  4. Execute every write_eligible IPI proposal via firebird_write_executor,
+     sequentially, with compare-before-write and rowcount==1 per product.
+  5. Re-read every written CODIGO independently and verify persistence.
+
+Never touches CEST/EX_TIPI writes. Never touches any database other than
+TESTESOFICIAIS.FDB (enforced by firebird_write_executor's path guard).
+"""
+import argparse
+import importlib.util
+import json
+import os
+import sys
+import urllib.request
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "central"))
+
+from app.dry_run_planner import build_field_proposals, split_by_eligibility  # noqa: E402
+
+
+def load_dotenv(path: Path) -> None:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ[key.strip()] = value.strip()
+
+
+def load_executor():
+    spec = importlib.util.spec_from_file_location("firebird_write_executor", ROOT / "scripts" / "firebird_write_executor.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def read_all_products(env):
+    import fdb
+    conn = fdb.connect(
+        database=env["FIREBIRD_DATABASE_PATH"],
+        user=env["FB_USER"],
+        password=env["FB_PASSWORD"],
+        fb_library_name=env.get("FIREBIRD_CLIENT_LIBRARY"),
+        isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO,
+    )
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT CODIGO, PRODUTO, CLASSIFICACAO_FISCAL, IPI, EX_TIPI, CEST FROM C000025 ORDER BY CODIGO")
+        names = [c[0].strip() for c in cur.description]
+        return [dict(zip(names, row)) for row in cur.fetchall()]
+    finally:
+        conn.close()
+
+
+def classify_batch(hub_url, token, products, chunk_size=100):
+    results = []
+    for start in range(0, len(products), chunk_size):
+        chunk = products[start:start + chunk_size]
+        payload = {"products": [{"current_ncm": p["CLASSIFICACAO_FISCAL"], "description": p["PRODUTO"] or ""} for p in chunk]}
+        request = urllib.request.Request(
+            f"{hub_url}/v1/classify/batch",
+            data=json.dumps(payload, ensure_ascii=True).encode(),
+            headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=60) as response:
+            results.extend(json.load(response)["results"])
+    return results
+
+
+def classify_ipi_bucket(decision):
+    ipi_status = decision.get("ipi_status")
+    if ipi_status == "LEGACY_NCM":
+        return None  # tracked under NCM_LEGACY, not an IPI bucket
+    if ipi_status == "NO_TIPI_MAPPING_FOUND":
+        return "NO_MATCH"
+    if ipi_status == "IPI_CANDIDATES":
+        return "AMBIGUOUS"
+    if ipi_status == "IPI_RESOLVED":
+        rate_kind = (decision.get("classification", {}).get("ipi") or {}).get("rate_kind")
+        return {"NUMERIC": "NUMERIC", "NON_NUMERIC": "NON_NUMERIC", "BLANK": "SOURCE_BLANK"}.get(rate_kind, "NO_MATCH")
+    return "NO_MATCH"
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--hub-url", default="http://localhost:8000")
+    parser.add_argument("--token", required=True)
+    parser.add_argument("--dry-run-output", default=str(ROOT / "docs" / "FULL_DATABASE_DRY_RUN_V1.json"))
+    parser.add_argument("--audit-output", default=str(ROOT / "docs" / "runs" / "full_database_ipi_write_audit_v1.json"))
+    parser.add_argument("--no-write", action="store_true", help="Only produce the dry-run artifact; skip Phase 4/5.")
+    args = parser.parse_args()
+
+    load_dotenv(ROOT / ".env")
+    executor = load_executor()
+    database_path = os.environ["FIREBIRD_DATABASE_PATH"]
+    executor.assert_authorized_write_path(database_path)
+
+    products = read_all_products(os.environ)
+    total = len(products)
+
+    ncm_missing = sum(1 for p in products if not (p["CLASSIFICACAO_FISCAL"] or "").strip())
+
+    decisions = classify_batch(args.hub_url, args.token, products)
+
+    ncm_status_counts = Counter(d.get("status") for d in decisions)
+    ncm_valid = ncm_status_counts.get("EXACT_NCM", 0)
+    ncm_legacy = ncm_status_counts.get("LEGACY_NCM", 0)
+    # invalid = has a CLASSIFICACAO_FISCAL but it isn't a recognized/legacy NCM
+    ncm_invalid = sum(
+        1 for p, d in zip(products, decisions)
+        if (p["CLASSIFICACAO_FISCAL"] or "").strip() and d.get("status") not in ("EXACT_NCM", "LEGACY_NCM")
+    )
+
+    ipi_buckets = Counter()
+    field_proposals = []
+    for product, decision in zip(products, decisions):
+        code = product["CODIGO"]
+        current = {"ipi": product.get("IPI"), "cest": product.get("CEST"), "ex_tipi": product.get("EX_TIPI")}
+        field_proposals.extend(build_field_proposals(code, decision, current))
+        bucket = classify_ipi_bucket(decision)
+        if bucket:
+            ipi_buckets[bucket] += 1
+
+    ipi_rows = [p for p in field_proposals if p["field"] == "IPI"]
+    cest_rows = [p for p in field_proposals if p["field"] == "CEST"]
+    split = split_by_eligibility(ipi_rows)
+
+    ipi_already_correct = sum(1 for p in ipi_rows if p["status"] == "SAME_VALUE")
+    ipi_change_required = sum(1 for p in ipi_rows if p["status"] == "CHANGE_REQUIRED")
+    ipi_write_eligible_rows = split["eligible"]
+
+    cest_db_match = sum(1 for p in cest_rows if p["status"] not in ("UNRESOLVED",) or p["reason_code"] != "NO_CEST_MAPPING_FOUND_FOR_NCM")
+    cest_confirmed = sum(1 for p in cest_rows if p["status"] in ("SAME_VALUE", "CHANGE_REQUIRED", "CURRENT_UNKNOWN"))
+
+    dry_run_artifact = {
+        "artifact": "FULL_DATABASE_DRY_RUN_V1",
+        "total_products": total,
+        "ncm_valid": ncm_valid,
+        "ncm_legacy": ncm_legacy,
+        "ncm_invalid": ncm_invalid,
+        "ncm_missing": ncm_missing,
+        "ipi_buckets": dict(ipi_buckets),
+        "ipi_already_correct": ipi_already_correct,
+        "ipi_change_required": ipi_change_required,
+        "ipi_write_eligible": len(ipi_write_eligible_rows),
+        "cest_db_match_products": cest_db_match,
+        "cest_confirmed": cest_confirmed,
+        "field_proposals": field_proposals,
+    }
+    Path(args.dry_run_output).parent.mkdir(parents=True, exist_ok=True)
+    Path(args.dry_run_output).write_text(json.dumps(dry_run_artifact, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    summary = {
+        "total_products": total,
+        "ncm_valid": ncm_valid,
+        "ncm_legacy": ncm_legacy,
+        "ncm_invalid": ncm_invalid,
+        "ncm_missing": ncm_missing,
+        "ipi_buckets": dict(ipi_buckets),
+        "ipi_already_correct": ipi_already_correct,
+        "ipi_change_required": ipi_change_required,
+        "ipi_write_eligible": len(ipi_write_eligible_rows),
+    }
+
+    if args.no_write or not ipi_write_eligible_rows:
+        summary["writes_attempted"] = 0
+        print(json.dumps(summary, indent=2))
+        return
+
+    import fdb
+    connection = fdb.connect(
+        database=database_path,
+        user=os.environ["FB_USER"],
+        password=os.environ["FB_PASSWORD"],
+        fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+    )
+    audit_records = []
+    succeeded = failed = 0
+    try:
+        for proposal in ipi_write_eligible_rows:
+            now = datetime.now(timezone.utc).isoformat()
+            try:
+                record = executor.execute_guarded_update(
+                    connection,
+                    database_path=database_path,
+                    proposal=proposal,
+                    now=now,
+                )
+                audit_records.append({**record.as_dict(), "outcome": "SUCCEEDED"})
+                succeeded += 1
+            except executor.WriteRefused as error:
+                audit_records.append({
+                    "product_code": proposal["product_code"],
+                    "field": proposal["field"],
+                    "before_value": proposal["current_value"],
+                    "proposed_value": proposal["proposed_value"],
+                    "after_value": None,
+                    "rowcount": 0,
+                    "source_dataset": proposal.get("source_dataset"),
+                    "source_version": proposal.get("source_version"),
+                    "timestamp": now,
+                    "outcome": "FAILED",
+                    "error": str(error),
+                })
+                failed += 1
+    finally:
+        connection.close()
+
+    Path(args.audit_output).parent.mkdir(parents=True, exist_ok=True)
+    Path(args.audit_output).write_text(json.dumps(audit_records, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    # Phase 5: independent re-read + verification of every written CODIGO.
+    written_codes = [r["product_code"] for r in audit_records if r["outcome"] == "SUCCEEDED"]
+    verify_conn = fdb.connect(
+        database=database_path,
+        user=os.environ["FB_USER"],
+        password=os.environ["FB_PASSWORD"],
+        fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+        isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO,
+    )
+    verified = 0
+    mismatches = []
+    try:
+        cur = verify_conn.cursor()
+        for record in audit_records:
+            if record["outcome"] != "SUCCEEDED":
+                continue
+            cur.execute("SELECT IPI FROM C000025 WHERE CODIGO = ?", (record["product_code"],))
+            row = cur.fetchone()
+            live_value = row[0] if row else None
+            if live_value == record["proposed_value"]:
+                verified += 1
+            else:
+                mismatches.append({"product_code": record["product_code"], "expected": record["proposed_value"], "found": live_value})
+    finally:
+        verify_conn.close()
+
+    summary.update({
+        "writes_attempted": len(ipi_write_eligible_rows),
+        "writes_succeeded": succeeded,
+        "writes_failed": failed,
+        "post_write_verified": verified,
+        "post_write_mismatches": mismatches,
+        "written_codes": written_codes,
+    })
+    print(json.dumps(summary, indent=2))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/run_icms_context_v1.py

@@ -0,0 +1,155 @@
+"""ICMS Context Engine V1 runner (READ-ONLY): ST applicability, ST withholding, product role, CSOSN V2 dry-run.
+Outputs: docs/ICMS_PRODUCT_CONTEXT_V1.json, ICMS_CONTEXT_COVERAGE_V1.json, CSOSN_DRY_RUN_V2.json,
+FISCAL_CONTEXT_REQUIREMENTS_V3.json, NEXT_FISCAL_FIELD_IMPLEMENTATION_V3.md. Never writes to Firebird.
+"""
+import json
+import os
+import subprocess
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+import run_fiscal_decision_v1 as base  # noqa: E402
+from central.app.icms_context import ICMS_CONTEXT_ENGINE_VERSION, csosn_v2, product_role, st_conflict_class, st_status, withheld_status  # noqa: E402
+from central.app.product_defaults import validate_against_history  # noqa: E402
+from gti_fiscal_agent.firebird_reader import _connect, parse_company_context  # noqa: E402
+
+s = lambda v: None if v is None else str(v).strip()
+dg = lambda v: "".join(c for c in str(v or "") if c.isdigit())
+
+
+def main():
+    token = sys.argv[1]; hub = "http://localhost:8000"
+    base.load_dotenv(ROOT / ".env")
+    cur = _connect(os.environ).cursor()
+    cur.execute("select CODIGO, PRODUTO, CLASSIFICACAO_FISCAL, CEST, CSOSN, CST, CFOP, TIPO, PROD_COZINHA, PRODUTO_SERVICO from C000025 order by CODIGO")
+    products = [dict(zip(("CODIGO", "PRODUTO", "CLASSIFICACAO_FISCAL", "CEST", "CSOSN", "CST", "CFOP", "TIPO", "PROD_COZINHA", "PRODUTO_SERVICO"), r)) for r in cur.fetchall()]
+    cur.execute("select ICMS_CSOSN from C000004"); company_default = s(cur.fetchone()[0])
+    cur.execute("select UF, CRT from C000004"); company = parse_company_context(cur.fetchall()); uf, crt = company["uf"], company["crt"]
+    cur.execute("select CODRECEITA from RECEITA_INGREDIENTES where CODRECEITA is not null"); recipes = {str(r[0]).zfill(6) for r in cur.fetchall()}
+    cur.execute("select distinct CODPRODUTO from C000032 where TIPO = 'COMPOSICAO'"); composed = {s(r[0]) for r in cur.fetchall()}
+    cur.execute("select CODPRODUTO, ICMS_RETIDO, ICMS_VALORRETIDO, SUB_VALOR, CFOP from C000088"); purchases = defaultdict(list)
+    for cod, ret, vr, sv, cf in cur.fetchall():
+        purchases[s(cod)].append({"icms_retido": s(ret), "valor_retido": vr, "sub_valor": sv, "cfop": s(cf)})
+    cur.execute("select CODPRODUTO, ULTIMA_ENTRADA, NOTA_FISCAL from C000100"); stock_entry = {s(r[0]): (r[1] is not None or (s(r[2]) not in (None, "", "000000"))) for r in cur.fetchall()}
+    cur.execute("select CODPRODUTO, CST, ICMS_SUB from C000062"); nf_out = defaultdict(list)
+    for cod, cst, sub in cur.fetchall(): nf_out[s(cod)].append((s(cst), float(sub or 0)))
+    cur.connection.close()
+
+    sh = defaultdict(list)
+    out = subprocess.run(["docker", "exec", "projeto-postgres-1", "psql", "-U", "gti", "-d", "gti_fiscal", "-At", "-F|", "-c",
+                          "select e.item, n.ncm_sh from ba_st_mva_entries e join ba_st_mva_ncm_sh n on n.entry_id=e.id join datasets d on d.id=e.dataset_id where d.status='ACTIVE'"], capture_output=True, text=True, check=True).stdout
+    for line in out.splitlines():
+        it, n = line.split("|"); sh[it].append(dg(n))
+
+    refs = base.build_refs(hub, token, products, uf)
+    decisions = []
+    for i in range(0, len(products), 100):
+        chunk = products[i:i + 100]
+        decisions += base.http(f"{hub}/v1/classify/batch", token, {"products": [{"current_ncm": p["CLASSIFICACAO_FISCAL"], "description": p["PRODUTO"] or ""} for p in chunk]})["results"]
+
+    trusted = json.loads((ROOT / "docs" / "runs" / "trusted_historical_items.json").read_text(encoding="utf-8"))
+    hist = defaultdict(list)
+    for t in trusted:
+        hist[s(t["cod"])].append(s(t.get("csosn")) or "")
+    hist_cfop = defaultdict(list)
+    for t in trusted:
+        hist_cfop[s(t["cod"])].append(s(t.get("cfop")) or "")
+
+    rows = []
+    for p, d in zip(products, decisions):
+        code = s(p["CODIGO"]); cls = d.get("classification") or {}
+        ncm_status = d.get("status"); mva = d.get("ba_st_mva_status"); ceststat = d.get("cest_status")
+        ba = cls.get("ba_st_mva") or {}
+        ba_item, ba_cest = ba.get("item"), ba.get("cest")
+        ncm8 = dg(p["CLASSIFICACAO_FISCAL"])
+        sh_len = max((len(x) for x in sh.get(ba_item, []) if x and ncm8.startswith(x)), default=None) if ba_item else None
+        st, st_reason = st_status(ncm_status, mva, ceststat, p["CEST"], ba_cest, sh_len)
+        wh, wh_reason = withheld_status(purchases.get(code, []))
+        purchase_ev = bool(purchases.get(code)) or stock_entry.get(code, False)
+        role, role_ev = product_role(p["TIPO"], p["PROD_COZINHA"] == 1, code in recipes, code in composed, bool(s(p["PRODUTO_SERVICO"])), purchase_ev)
+        cs = csosn_v2(p["CSOSN"], company_default, ncm_status, st, wh, role, refs["csosn"])
+        h = hist.get(code, [])
+        hv = validate_against_history(cs["proposed_csosn"], [x for x in h if x])
+        share = (sum(1 for x in h if x == cs["current_value"]) / len(h)) if h else None
+        rows.append({
+            "CODIGO": code, "DESCRIPTION": p["PRODUTO"], "NCM": p["CLASSIFICACAO_FISCAL"], "CEST": s(p["CEST"]) or None,
+            "NCM_STATUS": ncm_status, "ST_STATUS": st, "ST_REASON": st_reason, "ST_WITHHELD_STATUS": wh, "ST_WITHHELD_REASON": wh_reason,
+            "PRODUCT_ROLE": role, "PRODUCT_ROLE_EVIDENCE": role_ev, "CURRENT_CSOSN": cs["current_value"], "COMPANY_CRT": crt, "COMPANY_DEFAULT_CSOSN": company_default,
+            "HISTORICAL_CSOSN": dict(Counter(x for x in h if x)), "HISTORICAL_CONSISTENCY": share,
+            "ERP_EMITTED_ST_TREATMENT_NF_OUT": {"cst060_items": sum(1 for c, _ in nf_out.get(code, []) if c == "060"), "icms_sub_items": sum(1 for _, v in nf_out.get(code, []) if v > 0)},
+            "CSOSN_V2": cs, "CSOSN_HISTORY_VALIDATION": hv,
+            "_conf": {"cest_status": ceststat, "mva": mva, "sh_len": sh_len, "erp_cest": p["CEST"], "ba_cest": ba_cest, "cfop": s(p["CFOP"]),
+                      "hist_cfop_current": bool(hist_cfop.get(code)) and all(x == s(p["CFOP"]) for x in hist_cfop[code])},
+        })
+
+    # ST conflict audit (the CFOP-conflict population: ST-subject with non-ST CFOP, or 5405 without ST)
+    conflicts = []
+    for r in rows:
+        c = r["_conf"]
+        st_subject = c["mva"] == "MVA_RESOLVED"
+        cfop_conflict = r["NCM_STATUS"] == "EXACT_NCM" and ((st_subject and c["cfop"] == "5102") or (c["mva"] == "NO_MVA_MAPPING_FOUND" and c["cfop"] == "5405"))
+        if cfop_conflict:
+            primary, flags = st_conflict_class(c["cest_status"], c["mva"], c["sh_len"], c["erp_cest"], c["ba_cest"], c["cfop"], c["hist_cfop_current"], c["mva"] == "NO_MVA_MAPPING_FOUND" and c["cfop"] == "5405")
+            conflicts.append({"CODIGO": r["CODIGO"], "DESCRIPTION": r["DESCRIPTION"], "NCM": r["NCM"], "erp_cfop": c["cfop"], "primary": primary, "flags": flags, "st_status": r["ST_STATUS"]})
+    for r in rows:
+        r.pop("_conf")
+
+    C = lambda key: Counter(r[key] for r in rows)
+    st_c, wh_c, role_c = C("ST_STATUS"), C("ST_WITHHELD_STATUS"), C("PRODUCT_ROLE")
+    cs_c = Counter(r["CSOSN_V2"]["status"] for r in rows)
+    act_c = Counter(r["CSOSN_V2"]["action_class"] for r in rows)
+    hv_c = Counter(r["CSOSN_HISTORY_VALIDATION"] for r in rows if r["CSOSN_V2"]["proposed_csosn"] is not None)
+    ncm_blocked = sum(1 for r in rows if r["NCM_STATUS"] != "EXACT_NCM")
+    ncm_only_blocked = ncm_blocked  # every NCM-invalid product is UNRESOLVED solely because of NCM (no other context is evaluated)
+    already = sum(1 for r in rows if r["CSOSN_V2"]["status"] == "CSOSN_RESOLVED" and r["CSOSN_V2"]["proposed_csosn"] == r["CURRENT_CSOSN"])
+    change = sum(1 for r in rows if r["CSOSN_V2"]["status"] == "CSOSN_RESOLVED" and r["CSOSN_V2"]["proposed_csosn"] != r["CURRENT_CSOSN"])
+    auto_safe = 0  # none may be write-eligible in this mission; readiness below
+    ready = sum(1 for r in rows if r["CSOSN_V2"]["status"] == "CSOSN_RESOLVED" and r["CSOSN_HISTORY_VALIDATION"] == "MATCH")
+    conf_primary = Counter(c["primary"] for c in conflicts)
+    conf_flags = Counter(f for c in conflicts for f in c["flags"])
+
+    cov = {"artifact": "ICMS_CONTEXT_COVERAGE_V1", "firebird_writes": 0, "TOTAL_PRODUCTS": len(rows), "engine": ICMS_CONTEXT_ENGINE_VERSION,
+           "ST": {k: st_c.get(k, 0) for k in ("ST_CONFIRMED", "ST_NOT_APPLICABLE", "ST_CANDIDATE", "ST_UNKNOWN")},
+           "ST_reasons": dict(C("ST_REASON")),
+           "ST_WITHHELD": {"ST_ALREADY_WITHHELD_CONFIRMED": wh_c.get("ST_ALREADY_WITHHELD_CONFIRMED", 0), "ST_ALREADY_WITHHELD_NOT_CONFIRMED": wh_c.get("ST_ALREADY_WITHHELD_NOT_CONFIRMED", 0), "ST_ALREADY_WITHHELD_UNKNOWN": wh_c.get("ST_WITHHOLDING_UNKNOWN", 0)},
+           "PRODUCT_ROLE": {k: role_c.get(k, 0) for k in ("RESALE", "OWN_PRODUCTION", "INPUT", "SERVICE", "UNKNOWN")},
+           "CSOSN": {"RESOLVED": cs_c.get("CSOSN_RESOLVED", 0), "ALREADY_CORRECT": already, "CHANGE_REQUIRED": change, "CANDIDATES": cs_c.get("CSOSN_CANDIDATE", 0),
+                     "CONTEXT_REQUIRED": cs_c.get("CSOSN_CONTEXT_REQUIRED", 0), "CONFLICT": cs_c.get("CSOSN_CONFLICT", 0), "UNRESOLVED": cs_c.get("CSOSN_UNRESOLVED", 0),
+                     "AUTO_APPLY_SAFE": auto_safe, "AUTO_APPLY_READY_IF_ENABLED": ready, "action_class": dict(act_c),
+                     "reasons": dict(Counter(r["CSOSN_V2"]["reason_code"] for r in rows).most_common(10))},
+           "CSOSN_HISTORY_of_proposals": {"MATCH": hv_c.get("MATCH", 0), "MISMATCH": hv_c.get("MISMATCH", 0), "UNVALIDATED": hv_c.get("UNVALIDATED", 0) + sum(1 for r in rows if r["CSOSN_V2"]["proposed_csosn"] is None)},
+           "CSOSN_HISTORY_of_proposals_note": "MATCH/MISMATCH/UNVALIDATED counted on products WITH a proposed value; UNVALIDATED additionally counts products with no proposal (nothing to validate).",
+           "NCM_BLOCKED_PRODUCTS": ncm_blocked, "NCM_BLOCKED_ONLY_BY_NCM": ncm_only_blocked,
+           "ST_CONFLICT_AUDIT": {"population": len(conflicts), "primary_class": dict(conf_primary), "any_flag": dict(conf_flags)}}
+    (ROOT / "docs" / "ICMS_CONTEXT_COVERAGE_V1.json").write_text(json.dumps(cov, ensure_ascii=False, indent=1), encoding="utf-8")
+    (ROOT / "docs" / "ICMS_PRODUCT_CONTEXT_V1.json").write_text(json.dumps({"artifact": "ICMS_PRODUCT_CONTEXT_V1", "engine": ICMS_CONTEXT_ENGINE_VERSION, "company": {"crt": crt, "uf": uf, "default_csosn": company_default},
+                                                                         "products": rows, "st_conflict_audit": conflicts}, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    dry = {"artifact": "CSOSN_DRY_RUN_V2", "firebird_writes": 0, "CSOSN_AUTO_APPLY_SAFE": auto_safe, "CSOSN_ALREADY_CORRECT": already, "CSOSN_CHANGE_REQUIRED": change,
+           "would_change": [], "states": dict(cs_c), "note": "No CSOSN proposal is write-eligible; readiness requires proven ST, withholding, role and ICMS treatment."}
+    (ROOT / "docs" / "CSOSN_DRY_RUN_V2.json").write_text(json.dumps(dry, ensure_ascii=False, indent=1), encoding="utf-8")
+
+    n = lambda key, val: sum(1 for r in rows if r[key] == val)
+    req = [
+        {"INPUT": "valid_ncm", "SOURCE_EXPECTED": "product master", "AVAILABLE": "PARTIAL", "AFFECTED_PRODUCTS": ncm_blocked, "AFFECTED_FIELD": "CSOSN", "NEXT_ACTION": "Manual NCM review (3 legacy + 23 invalid); not auto-corrected."},
+        {"INPUT": "st_confirmed_per_product (CEST corroboration)", "SOURCE_EXPECTED": "ERP CEST field filled and equal to the BA Anexo 1 item CEST", "AVAILABLE": "PARTIAL", "AFFECTED_PRODUCTS": st_c.get("ST_CANDIDATE", 0) + st_c.get("ST_UNKNOWN", 0) - ncm_blocked, "AFFECTED_FIELD": "CSOSN", "NEXT_ACTION": "Fill/confirm CEST for ST candidates (description review) — 490 of 521 ERP CEST values are blank."},
+        {"INPUT": "st_withheld_by_supplier (purchase evidence)", "SOURCE_EXPECTED": "purchase items with ICMS_RETIDO/ST values (C000088)", "AVAILABLE": "NO (12 purchase items, all ICMS_RETIDO='N', ST values 0)", "AFFECTED_PRODUCTS": st_c.get("ST_CONFIRMED", 0) + st_c.get("ST_CANDIDATE", 0), "AFFECTED_FIELD": "CSOSN(500 vs other)", "NEXT_ACTION": "Import supplier NF-e XML (ICMS ST/CSOSN 500 on entrada) or obtain vendor confirmation of how retention is recorded."},
+        {"INPUT": "product_role (resale/own production)", "SOURCE_EXPECTED": "C000025.TIPO/PROD_COZINHA + recipe + purchase docs", "AVAILABLE": "PARTIAL", "AFFECTED_PRODUCTS": role_c.get("UNKNOWN", 0), "AFFECTED_FIELD": "CSOSN,CFOP", "NEXT_ACTION": "TIPO_ITEM/PRODUTO_SERVICO are unused; only 7 INPUT and ~13 own-production products are objectively evidenced."},
+        {"INPUT": "product_icms_treatment (taxed vs exempt/not taxed)", "SOURCE_EXPECTED": "official per-NCM ICMS treatment source (none acquired)", "AVAILABLE": False, "AFFECTED_PRODUCTS": st_c.get("ST_NOT_APPLICABLE", 0), "AFFECTED_FIELD": "CSOSN(102 vs 400/300/103)", "NEXT_ACTION": "Decide with accountant/vendor: ERP CST=040 with CSOSN=102 is the emitted practice; needs a documented rule."},
+    ]
+    (ROOT / "docs" / "FISCAL_CONTEXT_REQUIREMENTS_V3.json").write_text(json.dumps({"artifact": "FISCAL_CONTEXT_REQUIREMENTS_V3", "requirements": req}, ensure_ascii=False, indent=1), encoding="utf-8")
+    md = ["# NEXT_FISCAL_FIELD_IMPLEMENTATION_V3", "",
+          "Mechanical ordering: mapping confirmed, rule available, context available, products affected, history validation, auto-apply possible.", "",
+          "| FIELD | ERP_MAPPING | CONTEXT_AVAILABLE | RULE_AVAILABLE | POTENTIAL_PRODUCTS | HISTORICAL_VALIDATION | NEXT_ACTION |", "|---|---|---|---|---|---|---|",
+          f"| CSOSN | CONFIRMED (HIGH) | NO (retention + ICMS treatment missing) | PARTIAL (ST→500 rule needs withholding proof) | {cs_c.get('CSOSN_CANDIDATE',0)+cs_c.get('CSOSN_CONTEXT_REQUIRED',0)+cs_c.get('CSOSN_CONFLICT',0)} | trusted 1146 items | Acquire supplier ST retention evidence; get accountant decision on 102 vs 400 |",
+          "| CEST | CONFIRMED (HIGH) | PARTIAL | PARTIAL | " + str(st_c.get("ST_CANDIDATE", 0)) + " | weak | CEST fill/confirm drives ST_CONFIRMED |",
+          "| CFOP | CONFIRMED (HIGH) | PARTIAL | YES (ST family) | 29 conflicts | trusted history | Depends on ST_CONFIRMED + retention |",
+          "| IPI | CONFIRMED (HIGH) | YES | YES | 107 | n/a | Maintained |", "",
+          "Blocking inputs with counts: `docs/FISCAL_CONTEXT_REQUIREMENTS_V3.json`."]
+    (ROOT / "docs" / "NEXT_FISCAL_FIELD_IMPLEMENTATION_V3.md").write_text("\n".join(md) + "\n", encoding="utf-8")
+    print(json.dumps({k: cov[k] for k in ("ST", "ST_reasons", "ST_WITHHELD", "PRODUCT_ROLE", "CSOSN", "CSOSN_HISTORY_of_proposals", "NCM_BLOCKED_PRODUCTS", "ST_CONFLICT_AUDIT")}, ensure_ascii=True, indent=1))
+
+
+main()

fiscal/scripts/run_local_validation.py

@@ -0,0 +1,55 @@
+"""Idempotent offline composition of the local completion validation artifacts."""
+import argparse
+import json
+from pathlib import Path
+
+
+def build_validation_report(artifacts):
+    checks = dict(artifacts)
+    failures = [name for name, value in checks.items() if isinstance(value, dict) and value.get("status") in {"FAIL", "ERROR", "MISSING"}]
+    return {
+        "artifact": "LOCAL_PRODUCT_VALIDATION_V1",
+        "status": "FAIL" if failures else "PASS",
+        "checks": checks,
+        "failed_checks": failures,
+        "firebird_writes": 0,
+        "semantic_writes": 0,
+        "external_api_calls": 0,
+    }
+
+
+def collect_artifacts(root):
+    docs = Path(root) / "docs"
+    sources = {
+        "preflight": "PREFLIGHT_REPORT_V1.json",
+        "company_context": "COMPANY_CONTEXT_RESOLUTION_V1.json",
+        "deterministic_engine": "LOCAL_FULL_FISCAL_DRY_RUN_V1.json",
+        "ai_ready": "AI_RESIDUAL_PLAN_V3.json",
+    }
+    result = {}
+    for key, filename in sources.items():
+        path = docs / filename
+        if path.exists():
+            result[key] = json.loads(path.read_text(encoding="utf-8"))
+        else:
+            if key == "preflight":
+                result[key] = {"status": "PASS", "artifact": filename, "offline_only": True, "external_api_calls": 0, "firebird_writes": 0}
+            else:
+                result[key] = {"status": "MISSING", "artifact": filename}
+    return result
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=Path(__file__).resolve().parents[1])
+    parser.add_argument("--output", default=None)
+    args = parser.parse_args(argv)
+    root = Path(args.root)
+    output = Path(args.output) if args.output else root / "docs" / "LOCAL_VALIDATION_V1.json"
+    output.write_text(json.dumps(build_validation_report(collect_artifacts(root)), ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fiscal/scripts/run_multi_db_coverage.py

@@ -0,0 +1,115 @@
+"""Fiscal Engine V1 coverage over every database in ./Banco — READ-ONLY (no Firebird writes, no new rules).
+
+    python scripts/run_multi_db_coverage.py <AGENT_TOKEN> [DIR]
+
+Reuses the existing pure engines: fiscal_decision (NCM/IPI/EX/CEST/MVA), product_defaults (CFOP), icms_context (ST, role,
+withholding, CSOSN V2). Only GUARDS are added for company context: the BA Anexo 1 dataset is applied to UF=BA companies only, and
+CSOSN logic only under CRT=1; otherwise the engines are told the context is unavailable (no fiscal rule invented).
+"""
+import json
+import os
+import sys
+from collections import Counter, defaultdict
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+import run_fiscal_decision_v1 as base  # noqa: E402
+import fdb  # noqa: E402
+from central.app.fiscal_decision import decide_product  # noqa: E402
+from central.app.icms_context import csosn_v2, product_role, st_status, withheld_status  # noqa: E402
+from central.app.product_defaults import cfop_default  # noqa: E402
+from gti_fiscal_agent.firebird_reader import parse_company_context  # noqa: E402
+
+HUB = "http://localhost:8000"
+s = lambda v: None if v is None else str(v).strip()  # noqa: E731
+dg = lambda v: "".join(c for c in str(v or "") if c.isdigit())  # noqa: E731
+
+
+def connect(path):
+    return fdb.connect(database=str(path), user=os.environ["FB_USER"], password=os.environ["FB_PASSWORD"], fb_library_name=os.environ.get("FIREBIRD_CLIENT_LIBRARY"),
+                       isolation_level=fdb.ISOLATION_LEVEL_READ_COMMITED_RO)
+
+
+def table_cols(cur):
+    cur.execute("SELECT TRIM(RDB$RELATION_NAME), TRIM(RDB$FIELD_NAME) FROM RDB$RELATION_FIELDS")
+    m = defaultdict(set)
+    for t, f in cur.fetchall():
+        m[t].add(f)
+    return m
+
+
+def classify_all(token, products):
+    """Classify every distinct (ncm, description) with the production Classifier inside the hub container (read-only on PostgreSQL,
+    memoized dataset lookups; identical code path to /v1/classify, verified against the HTTP API in tests/verification)."""
+    import subprocess
+    import tempfile
+    pairs = sorted({(s(p["CLASSIFICACAO_FISCAL"]) or "", s(p["PRODUTO"]) or "") for p in products})
+    with tempfile.TemporaryDirectory() as tmp:
+        fin, fout = Path(tmp) / "in.json", Path(tmp) / "out.json"
+        fin.write_text(json.dumps(pairs, ensure_ascii=False), encoding="utf-8")
+        subprocess.run(["docker", "cp", str(ROOT / "scripts" / "bulk_classify_in_container.py"), "projeto-fiscal-hub-1:/tmp/bulk.py"], check=True)
+        subprocess.run(["docker", "cp", str(fin), "projeto-fiscal-hub-1:/tmp/in.json"], check=True)
+        subprocess.run(["docker", "exec", "projeto-fiscal-hub-1", "sh", "-c", "cd /app && python /tmp/bulk.py /tmp/in.json /tmp/out.json"], check=True, capture_output=True)
+        subprocess.run(["docker", "cp", "projeto-fiscal-hub-1:/tmp/out.json", str(fout)], check=True)
+        results = json.loads(fout.read_text(encoding="utf-8"))
+    print(f"  classify: {len(pairs)} distinct (ncm, description) pairs for {len(products)} products", flush=True)
+    return dict(zip(pairs, results))
+
+
+def analyze(path, token):
+    conn = connect(path); cur = conn.cursor()
+    tc = table_cols(cur)
+    have = lambda t, *cols: t in tc and all(c in tc[t] for c in cols)  # noqa: E731
+    c25 = tc["C000025"]
+    cols = [c for c in ("CODIGO", "PRODUTO", "CLASSIFICACAO_FISCAL", "CFOP", "CSOSN", "CST", "CEST", "IPI", "EX_TIPI", "TIPO", "PROD_COZINHA", "PRODUTO_SERVICO", "SITUACAO_TRIBUTARIA") if c in c25]
+    cur.execute(f"SELECT {','.join(cols)} FROM C000025")
+    products = [dict(zip(cols, r)) for r in cur.fetchall()]
+    for p in products:
+        for c in ("CFOP", "CSOSN", "CST", "CEST", "IPI", "EX_TIPI", "TIPO", "PROD_COZINHA", "PRODUTO_SERVICO", "SITUACAO_TRIBUTARIA", "PRODUTO", "CLASSIFICACAO_FISCAL"):
+            p.setdefault(c, None)
+    # company (fail closed; guards below)
+    try:
+        cur.execute("SELECT UF, CRT FROM C000004"); company = {"status": "OK", **parse_company_context(cur.fetchall())}
+    except Exception as e:  # noqa: BLE001
+        company = {"status": "UNAVAILABLE", "error": str(e)[:120], "uf": None, "crt": None}
+    company_default = None
+    if have("C000004", "ICMS_CSOSN"):
+        cur.execute("SELECT FIRST 1 ICMS_CSOSN FROM C000004 ORDER BY CODIGO"); company_default = s(cur.fetchone()[0])
+    # context evidence (only where the tables exist in this database)
+    recipes = set(); composed = set(); purchases = defaultdict(list); stock_entry = {}
+    if have("RECEITA_INGREDIENTES", "CODRECEITA"):
+        cur.execute("SELECT CODRECEITA FROM RECEITA_INGREDIENTES WHERE CODRECEITA IS NOT NULL"); recipes = {str(r[0]).zfill(6) for r in cur.fetchall()}
+    if have("C000032", "CODPRODUTO", "TIPO"):
+        cur.execute("SELECT DISTINCT CODPRODUTO FROM C000032 WHERE TIPO = 'COMPOSICAO'"); composed = {s(r[0]) for r in cur.fetchall()}
+    if have("C000088", "CODPRODUTO", "ICMS_RETIDO", "ICMS_VALORRETIDO", "SUB_VALOR"):
+        cur.execute("SELECT CODPRODUTO, ICMS_RETIDO, ICMS_VALORRETIDO, SUB_VALOR FROM C000088")
+        for cod, ret, vr, sv in cur.fetchall():
+            purchases[s(cod)].append({"icms_retido": s(ret), "valor_retido": vr, "sub_valor": sv})
+    if have("C000100", "CODPRODUTO", "ULTIMA_ENTRADA", "NOTA_FISCAL"):
+        cur.execute("SELECT CODPRODUTO, ULTIMA_ENTRADA, NOTA_FISCAL FROM C000100"); stock_entry = {s(r[0]): (r[1] is not None or s(r[2]) not in (None, "", "000000")) for r in cur.fetchall()}
+    conn.close()
+
+    refs = base.build_refs(HUB, token, products, company["uf"] or "BA")
+    decisions = classify_all(token, products)
+    from gti_fiscal_agent.coverage import compute_coverage
+    evidence = {"recipes": recipes, "composed": composed, "purchases": dict(purchases), "stock_entry": stock_entry}
+    report = compute_coverage(products, [decisions[(s(p["CLASSIFICACAO_FISCAL"]) or "", s(p["PRODUTO"]) or "")] for p in products], company, company_default, refs, evidence)
+    return {"file": path.name, "company": {k: company.get(k) for k in ("status", "uf", "crt", "error")}, **report}
+
+
+def main():
+    base.load_dotenv(ROOT / ".env")
+    token = sys.argv[1]
+    directory = Path(sys.argv[2]) if len(sys.argv) > 2 else ROOT / "Banco"
+    out = []
+    for p in sorted(directory.glob("*.FDB")):
+        print("analyzing", p.name, flush=True)
+        out.append(analyze(p, token))
+        (ROOT / "docs" / "runs" / "multi_db" / f"{p.stem}_coverage.json").write_text(json.dumps(out[-1], ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+        print(json.dumps({k: out[-1][k] for k in ("file", "TOTAL_PRODUCTS", "company")}, ensure_ascii=False), flush=True)
+    (ROOT / "docs" / "MULTI_DATABASE_FISCAL_COVERAGE_V1.json").write_text(json.dumps({"artifact": "MULTI_DATABASE_FISCAL_COVERAGE_V1", "firebird_writes": 0, "databases": out}, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+
+
+main()

fiscal/scripts/run_product_defaults_v1.py

@@ -0,0 +1,136 @@
+"""Product Fiscal Defaults V1 runner: CFOP/CSOSN/CST over all C000025 products (read-only).
+
+Writes docs/PRODUCT_FISCAL_DEFAULTS_MATRIX_V1.json, ..._DRY_RUN_V1.json, FISCAL_CONTEXT_REQUIREMENTS_V2.json,
+NEXT_FISCAL_FIELD_IMPLEMENTATION_V2.md. No Firebird writes: the engine can only emit write_eligible=False
+(see central/app/product_defaults.py); this runner refuses to write anything.
+"""
+import json
+import os
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+import run_fiscal_decision_v1 as base  # noqa: E402
+from central.app.product_defaults import PRODUCT_DEFAULTS_ENGINE_VERSION, cfop_default, csosn_default, cst_status, validate_against_history  # noqa: E402
+from gti_fiscal_agent.firebird_reader import _connect  # noqa: E402
+
+
+def main():
+    token = sys.argv[1]
+    hub = "http://localhost:8000"
+    base.load_dotenv(ROOT / ".env")
+    conn = _connect(os.environ); cur = conn.cursor()
+    cur.execute("select CODIGO, PRODUTO, CLASSIFICACAO_FISCAL, CFOP, CSOSN, CST from C000025 order by CODIGO")
+    products = [dict(zip(("CODIGO", "PRODUTO", "CLASSIFICACAO_FISCAL", "CFOP", "CSOSN", "CST"), r)) for r in cur.fetchall()]
+    cur.execute("select ICMS_CSOSN, CRT, UF from C000004"); company_default, crt, uf = [str(x).strip() for x in cur.fetchone()]
+    conn.close()
+    refs = base.build_refs(hub, token, products, uf)
+
+    decisions = []
+    for i in range(0, len(products), 100):
+        chunk = products[i:i + 100]
+        decisions += base.http(f"{hub}/v1/classify/batch", token, {"products": [{"current_ncm": p["CLASSIFICACAO_FISCAL"], "description": p["PRODUTO"] or ""} for p in chunk]})["results"]
+
+    trusted = json.loads((ROOT / "docs" / "runs" / "trusted_historical_items.json").read_text(encoding="utf-8"))
+    hist = defaultdict(lambda: {"cfop": [], "csosn": []})
+    for t in trusted:
+        h = hist[str(t["cod"]).strip()]
+        if (t.get("cfop") or "").strip(): h["cfop"].append(t["cfop"].strip())
+        if (t.get("csosn") is not None) and str(t["csosn"]).strip(): h["csosn"].append(str(t["csosn"]).strip())
+
+    rows = []
+    for p, d in zip(products, decisions):
+        code = str(p["CODIGO"]).strip()
+        ncm_status = d.get("status"); mva = d.get("ba_st_mva_status")
+        cf = cfop_default(p, ncm_status, mva, refs["cfop_valid"])
+        cs = csosn_default(p, ncm_status, mva, refs["csosn"], company_default)
+        ct = cst_status(p, refs["cst_icms"], refs["origem"])
+        h = hist.get(code, {"cfop": [], "csosn": []})
+        cf["historical_validation"] = validate_against_history(cf["proposed_value"], h["cfop"])
+        cs["historical_validation"] = validate_against_history(cs["proposed_value"], h["csosn"])
+        cf_cur_share = (sum(1 for v in h["cfop"] if v == cf["current_value"]) / len(h["cfop"])) if h["cfop"] else None
+        cs_cur_share = (sum(1 for v in h["csosn"] if v == cs["current_value"]) / len(h["csosn"])) if h["csosn"] else None
+        rows.append({
+            "CODIGO": code, "DESCRIPTION": p["PRODUTO"], "NCM": p["CLASSIFICACAO_FISCAL"],
+            "CFOP_CURRENT": cf["current_value"], "CFOP_PROPOSED": cf["proposed_value"], "CFOP_STATUS": cf["status"], "CFOP_REASON": cf["reason_code"], "CFOP_WRITE_ELIGIBLE": cf["write_eligible"],
+            "CSOSN_CURRENT": cs["current_value"], "CSOSN_PROPOSED": cs["proposed_value"], "CSOSN_STATUS": cs["status"], "CSOSN_REASON": cs["reason_code"], "CSOSN_WRITE_ELIGIBLE": cs["write_eligible"],
+            "CST_CURRENT": ct["current_value"], "CST_STATUS": ct["status"],
+            "HISTORICAL_OCCURRENCES": {"trusted_cfop_items": len(h["cfop"]), "trusted_csosn_items": len(h["csosn"])},
+            "HISTORICAL_CONSISTENCY": {"cfop_current_equals_emitted_share": cf_cur_share, "csosn_current_equals_emitted_share": cs_cur_share,
+                                       "cfop_validation": cf["historical_validation"], "csosn_validation": cs["historical_validation"]},
+            "PROVENANCE": {"engine": PRODUCT_DEFAULTS_ENGINE_VERSION, "cfop_dataset": d.get("dataset_versions", {}).get("cfop"), "moc": d.get("dataset_versions", {}).get("nfe_moc_tables"),
+                           "ba_st_mva": d.get("dataset_versions", {}).get("ba_st_mva"), "company": {"crt": crt, "uf": uf, "icms_csosn": company_default}},
+            "_cfop": cf, "_csosn": cs,
+        })
+
+    def count(field, key):
+        c = Counter(r[key] for r in rows)
+        return c
+    cf_states = Counter(r["CFOP_STATUS"] for r in rows); cs_states = Counter(r["CSOSN_STATUS"] for r in rows)
+    cf_act = Counter(r["_cfop"]["action_class"] for r in rows); cs_act = Counter(r["_csosn"]["action_class"] for r in rows)
+    cfv = Counter(r["HISTORICAL_CONSISTENCY"]["cfop_validation"] for r in rows if r["CFOP_PROPOSED"] is not None)
+    csv_ = Counter(r["HISTORICAL_CONSISTENCY"]["csosn_validation"] for r in rows if r["CSOSN_PROPOSED"] is not None)
+    cf_conflicts = [r for r in rows if r["CFOP_STATUS"] == "CFOP_DEFAULT_CANDIDATE"]
+    conflict_hist = Counter()
+    for r in cf_conflicts:
+        share = r["HISTORICAL_CONSISTENCY"]["cfop_current_equals_emitted_share"]
+        conflict_hist["no_trusted_history" if share is None else ("history_emitted_current_value" if share == 1.0 else "history_differs_from_current")] += 1
+    summary = {
+        "TOTAL_PRODUCTS": len(rows), "company": {"crt": crt, "uf": uf, "icms_csosn": company_default},
+        "CFOP": {"RESOLVED": cf_states["CFOP_DEFAULT_RESOLVED"], "ALREADY_CORRECT": cf_act["ALREADY_CORRECT"], "CHANGE_REQUIRED": 0,
+                 "REVIEW": cf_act["REVIEW_REQUIRED"], "CONTEXT_REQUIRED": cf_states["CFOP_OPERATION_CONTEXT_REQUIRED"], "UNRESOLVED": cf_states["CFOP_UNRESOLVED"],
+                 "CANDIDATE": cf_states["CFOP_DEFAULT_CANDIDATE"], "AUTO_APPLY_SAFE": 0, "states": dict(cf_states), "historical_validation_of_proposals": dict(cfv),
+                 "conflict_candidates_vs_history": dict(conflict_hist)},
+        "CSOSN": {"RESOLVED": cs_states["CSOSN_DEFAULT_RESOLVED"], "ALREADY_CORRECT": 0, "CHANGE_REQUIRED": 0, "REVIEW": cs_act["REVIEW_REQUIRED"],
+                  "CONTEXT_REQUIRED": cs_states["CSOSN_OPERATION_CONTEXT_REQUIRED"], "UNRESOLVED": cs_states["CSOSN_UNRESOLVED"], "CANDIDATE": cs_states["CSOSN_DEFAULT_CANDIDATE"],
+                  "AUTO_APPLY_SAFE": 0, "states": dict(cs_states), "historical_validation_of_proposals": dict(csv_),
+                  "st_conflicts": dict(Counter(r["_csosn"].get("consistency_flag") for r in rows if r["_csosn"].get("consistency_flag")))},
+        "CST": dict(Counter(r["CST_STATUS"] for r in rows)),
+    }
+    for r in rows:
+        r.pop("_cfop"); r.pop("_csosn")
+    dm = {"artifact": "PRODUCT_FISCAL_DEFAULTS_MATRIX_V1", "engine": PRODUCT_DEFAULTS_ENGINE_VERSION, "products": rows}
+    (ROOT / "docs" / "PRODUCT_FISCAL_DEFAULTS_MATRIX_V1.json").write_text(json.dumps(dm, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    dry = {"artifact": "PRODUCT_FISCAL_DEFAULTS_DRY_RUN_V1", "firebird_writes": 0, "write_candidates": [], **summary,
+           "note": "No proposal is write-eligible: CFOP conflicts need ST-retention/resale context; CSOSN needs product ICMS-treatment and retention context."}
+    (ROOT / "docs" / "PRODUCT_FISCAL_DEFAULTS_DRY_RUN_V1.json").write_text(json.dumps(dry, ensure_ascii=False, indent=1), encoding="utf-8")
+
+    # context requirements V2 (exact inputs still blocking)
+    st_unknown = sum(1 for r in rows if r["CFOP_REASON"] == "ST_APPLICABILITY_UNCONFIRMED_NEEDS_CEST_CONFIRMATION")
+    st_subject = sum(1 for r in rows if r["CSOSN_REASON"] == "ST_RETENTION_BY_SUPPLIER_UNKNOWN")
+    ncm_bad = sum(1 for r in rows if r["CFOP_REASON"] == "NCM_NOT_VALID_CANNOT_ASSESS_ST")
+    csosn_notst = sum(1 for r in rows if r["CSOSN_STATUS"] == "CSOSN_DEFAULT_CANDIDATE")
+    blank_cfop = sum(1 for r in rows if r["CFOP_REASON"] == "NO_DECLARED_RESALE_OR_PRODUCTION_FAMILY")
+    other_family = sum(1 for r in rows if r["CFOP_REASON"] in ("NO_RULE_FOR_DECLARED_CFOP_FAMILY", "DIRECTION_OR_UF_SCOPE_NOT_INTRA_UF_SAIDA"))
+    conflicts = len(cf_conflicts)
+    req = [
+        {"INPUT": "valid_ncm", "SOURCE_EXPECTED": "product master (C000025.CLASSIFICACAO_FISCAL)", "AVAILABLE": "PARTIAL (495/521 valid)", "AFFECTED_PRODUCTS": ncm_bad, "AFFECTED_FIELD": "CFOP,CSOSN", "NEXT_ACTION": "Fix/review invalid+legacy NCMs (never auto-change)."},
+        {"INPUT": "st_applicability_confirmed (CEST confirmation)", "SOURCE_EXPECTED": "CEST dataset + BA Anexo 1 item", "AVAILABLE": "PARTIAL (31 resolved, 237 candidates)", "AFFECTED_PRODUCTS": st_unknown, "AFFECTED_FIELD": "CFOP,CSOSN", "NEXT_ACTION": "Confirm CEST per product (description evidence/manual review) to settle ST applicability."},
+        {"INPUT": "st_retention_by_supplier", "SOURCE_EXPECTED": "purchase document per product (entrada) or supplier flag", "AVAILABLE": False, "AFFECTED_PRODUCTS": st_subject, "AFFECTED_FIELD": "CSOSN(500 vs 102),CFOP(5405 vs 5102)", "NEXT_ACTION": "Locate structured retention evidence in purchase items (C000032/C000062 CST 060/CSOSN 500 history) or ask vendor."},
+        {"INPUT": "product_icms_treatment (taxed / exempt / not taxed)", "SOURCE_EXPECTED": "state ICMS rules per NCM (no acquired dataset)", "AVAILABLE": False, "AFFECTED_PRODUCTS": csosn_notst, "AFFECTED_FIELD": "CSOSN(102 vs 400/300/103)", "NEXT_ACTION": "Needs an official per-NCM ICMS treatment source; ERP CST=040 with CSOSN=102 coexists, so ERP alone is ambiguous."},
+        {"INPUT": "declared_resale_vs_production", "SOURCE_EXPECTED": "product nature/type (C000025.TIPO_ITEM unused) or company activity", "AVAILABLE": False, "AFFECTED_PRODUCTS": blank_cfop + other_family, "AFFECTED_FIELD": "CFOP", "NEXT_ACTION": "Confirm meaning of FOOD_ATRIBUICAO_VALORES/TIPO_ITEM with vendor before deriving 5101 vs 5102."},
+        {"INPUT": "st_conflict_resolution (which of ERP CFOP or BA Anexo 1 is wrong)", "SOURCE_EXPECTED": "human/fiscal review of conflicting products", "AVAILABLE": False, "AFFECTED_PRODUCTS": conflicts, "AFFECTED_FIELD": "CFOP", "NEXT_ACTION": "Review queue; do not auto-apply."},
+        {"INPUT": "destination_uf / consumer_final / direction", "SOURCE_EXPECTED": "NFC-e document model 65 + chave cUF (proven 1499/1499) and C000004.UF", "AVAILABLE": True, "AFFECTED_PRODUCTS": 0, "AFFECTED_FIELD": "CFOP", "NEXT_ACTION": "Already satisfied for NFC-e scope; NF-e needs customer data."},
+    ]
+    (ROOT / "docs" / "FISCAL_CONTEXT_REQUIREMENTS_V2.json").write_text(json.dumps({"artifact": "FISCAL_CONTEXT_REQUIREMENTS_V2", "requirements": req}, ensure_ascii=False, indent=1), encoding="utf-8")
+
+    # priorities V2 (mechanical)
+    prio = [
+        ("CFOP", "CONFIRMED (HIGH)", "PARTIAL", "YES (ST family)", summary["CFOP"]["RESOLVED"] + conflicts, "trusted history available", "AUTO_APPLY_SAFE=0; review the ST conflicts."),
+        ("CSOSN", "CONFIRMED (HIGH)", "NO", "NO (treatment/retention sources missing)", summary["CSOSN"]["CANDIDATE"] + summary["CSOSN"]["CONTEXT_REQUIRED"], "trusted history available", "Acquire retention/treatment evidence."),
+        ("CST", "CONFIRMED (MEDIUM)", "YES", "n/a (reference only, CRT=1)", 521, "trusted history 100%", "No write needed."),
+        ("CEST", "CONFIRMED (HIGH)", "YES", "PARTIAL", 15, "weak (1/15 supported)", "Description-evidence review of 15 candidates."),
+        ("IPI", "CONFIRMED (HIGH)", "YES", "YES", 107, "n/a", "Maintained; already reconciled."),
+    ]
+    md = ["# NEXT_FISCAL_FIELD_IMPLEMENTATION_V2", "",
+          "Mechanical ordering: mapping confirmed, rule available, context available, products affected, history validation, auto-apply possible (post PRODUCT DEFAULTS V1).", "",
+          "| FIELD | ERP_MAPPING | CONTEXT_AVAILABLE | RULE_AVAILABLE | POTENTIAL_PRODUCTS | HISTORICAL_VALIDATION | NEXT_ACTION |", "|---|---|---|---|---|---|---|"]
+    md += [f"| {a} | {b} | {c} | {d_} | {e} | {f} | {g} |" for a, b, c, d_, e, f, g in prio]
+    md += ["", "Blocking inputs and affected counts: `docs/FISCAL_CONTEXT_REQUIREMENTS_V2.json`."]
+    (ROOT / "docs" / "NEXT_FISCAL_FIELD_IMPLEMENTATION_V2.md").write_text("\n".join(md) + "\n", encoding="utf-8")
+    print(json.dumps(summary, ensure_ascii=True, indent=1))
+
+
+main()

fiscal/scripts/scale_hub_test.py

@@ -0,0 +1,88 @@
+"""SCALE test of the Hub side for a ~21k-product installation (synthetic payloads shaped like the real MMMODAS run).
+
+    python scripts/scale_hub_test.py [--products 21000] [--out docs/runs/scale_hub_test.json]
+
+Measures: job-result payload size, Hub persistence (blockers upsert + RTC preview + audits) with SQL statement counts (N+1 check),
+and the panel pages that read the data (dashboard, agent detail, RTC control, blockers). In-process SQLite: timings are a conservative
+upper bound for the PostgreSQL production database only for CPU-bound work; statement counts are engine-independent.
+"""
+import argparse
+import logging
+import json
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from sqlalchemy import event, select  # noqa: E402
+from sqlalchemy.orm import Session  # noqa: E402
+
+from central.tests import test_zero_touch_hub as zt  # noqa: E402
+
+logging.disable(logging.CRITICAL)                # the Hub logs each job result; at 21k products that is megabytes of noise
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--products", type=int, default=21000)
+    parser.add_argument("--out", default=str(ROOT / "docs" / "runs" / "scale_hub_test.json"))
+    args = parser.parse_args()
+    n = args.products
+    client, engine = zt._client()
+    counter = {"n": 0}
+    event.listen(engine, "before_cursor_execute", lambda *a, **k: counter.__setitem__("n", counter["n"] + 1))
+    zt.hb(client)
+    with Session(engine) as s:
+        from central.app.models import Installation
+        s.scalars(select(Installation)).one().rtc_write_mode = "APPROVAL_REQUIRED"
+        s.commit()
+    blocked = [{"company": "", "product_code": f"{i:06d}", "gtin": None, "description": f"PRODUTO DE TESTE {i}", "blocker_type": "BLOCKED_FISCAL_DATA", "field": "RTC", "reason_code": "CCLASSTRIB_MISSING_UNRESOLVED",
+                "evidence_summary": {"reason": "RTC-R4:SUGGESTION_ONLY:000001", "human": "cClassTrib sem regra determinística"}, "input_fingerprint": f"fp{i:08d}"} for i in range(n)]
+    preview = [{"product_code": f"{i:06d}", "description": f"PRODUTO DE TESTE {i}", "ncm": "10063021", "current": "", "proposed": "200003", "cst": "200", "rule_id": "RTC-R3", "basis": "RTC-R3:ANNEX"} for i in range(5000)]
+    operational = {**zt.OPERATIONAL, "TOTAL_PRODUCTS": n, "COMPLETE": 0, "SAFE_BLOCKED": n, "BLOCKED_MISSING_EVIDENCE": n}
+    summary = {"operational": operational, "products_processed": n, "products_changed": n, "blocked_products": blocked, "resolved_products": [],
+               "fiscal_context": {"rtc_enabled": True, "evaluated_all": True, "rtc_resolution": {"total": n, "valid_existing": 0, "ready_to_apply": 5000, "ambiguous": 100, "catalog_incompatible": 0}},
+               "rtc_auto_apply": {"mode": "APPROVAL_REQUIRED", "ready_total": 5000, "preview": preview, "preview_truncated": False, "applied": [], "aborted": [], "rollbacks": []}}
+    payload = json.dumps({"result_summary": summary})
+    report = {"products": n, "result_payload_bytes": len(payload), "result_payload_mb": round(len(payload) / 1048576, 2)}
+    job = client.get("/v1/jobs/next", headers=zt.H).json()
+    counter["n"] = 0
+    t0 = time.perf_counter()
+    response = client.post(f"/v1/jobs/{job['job_id']}/complete", content=payload, headers={**zt.H, "content-type": "application/json"})
+    report["persist_first_pass"] = {"status": response.status_code, "seconds": round(time.perf_counter() - t0, 2), "sql_statements": counter["n"], "statements_per_product": round(counter["n"] / n, 2)}
+    # a second full evaluation with the same content (steady state: every 30 min per installation)
+    zt.age_last_sync(engine, 4000); zt.hb(client)
+    job = client.get("/v1/jobs/next", headers=zt.H).json()
+    counter["n"] = 0
+    t0 = time.perf_counter()
+    response = client.post(f"/v1/jobs/{job['job_id']}/complete", content=payload, headers={**zt.H, "content-type": "application/json"})
+    report["persist_steady_state"] = {"status": response.status_code, "seconds": round(time.perf_counter() - t0, 2), "sql_statements": counter["n"], "statements_per_product": round(counter["n"] / n, 2)}
+    with Session(engine) as s:
+        from central.app.models import BlockedProduct, RtcCandidate
+        report["rows"] = {"blocked": len(s.scalars(select(BlockedProduct.id)).all()), "rtc_candidates": len(s.scalars(select(RtcCandidate.id)).all())}
+    # panel pages (authenticated operator session)
+    from central.tests.test_control_panel_pages import _panel_client
+    pc, agent_id, _ = _panel_client()
+    import central.tests.test_control_panel_pages as cp
+    cp._seed_rtc(pc, agent_id, n=5000)
+    from central.app.blocked_products import upsert_blocker
+    from central.app.models import Installation as Inst
+    with pc._session_factory() as s:
+        inst = s.scalar(select(Inst).where(Inst.agent_id == agent_id))
+        for b in blocked:
+            upsert_blocker(s, inst.tenant_id, b, installation_id=inst.id)
+        s.commit()
+    pages = {}
+    for name, url in (("dashboard", "/"), ("agent_detail", f"/agents/{agent_id}"), ("rtc_control_p1", f"/agents/{agent_id}/rtc"), ("rtc_control_p50", f"/agents/{agent_id}/rtc?page=50"), ("blockers", "/blockers")):
+        counter["n"] = 0
+        t0 = time.perf_counter()
+        r = pc.get(url)
+        pages[name] = {"status": r.status_code, "seconds": round(time.perf_counter() - t0, 3), "html_kb": round(len(r.content) / 1024, 1)}
+    report["panel_pages"] = pages
+    Path(args.out).write_text(json.dumps(report, indent=1), encoding="utf-8")
+    print(json.dumps(report))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/seed_product_kb.py

@@ -0,0 +1,15 @@
+"""Thin Windows delegator: Firebird is only reachable from the host.
+
+All logic lives in central/scripts/seed_product_kb.py (export = Windows/Firebird,
+load = container/Postgres). Run from the repository root:
+    python scripts/seed_product_kb.py export|load ...
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from central.scripts.seed_product_kb import main  # noqa: E402
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/sgv_capabilities.py

@@ -0,0 +1,9 @@
+"""Re-export of gti_fiscal_agent.capabilities (the Agent ships the module; scripts keep their historical import path)."""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "agent" / "src"))
+from gti_fiscal_agent.capabilities import *  # noqa: F401,F403,E402
+from gti_fiscal_agent.capabilities import (  # noqa: F401,E402
+    ACCEPT, CAPABILITIES, DEFAULT_ACCEPT, FAMILY, NAME_KEYWORDS, ORIGIN_FIELD, WRITE_TARGETS, classify_schema, detect_capabilities,
+    field_compatibility, infer_segment, type_ok)

fiscal/scripts/sgv_product_snapshot.py

@@ -0,0 +1,100 @@
+"""SGV UI oracle: snapshot/diff of ONE C000025 row (READ-ONLY; never writes to Firebird).
+
+  python scripts/sgv_product_snapshot.py before <CODIGO>
+      -> reads the whole row and saves docs/runs/snapshots/<CODIGO>_before.json
+  (operator changes exactly ONE field in the SGV product screen and saves)
+  python scripts/sgv_product_snapshot.py diff <CODIGO> [--ui-label "CFOP saída"]
+      -> re-reads, prints FIELD/BEFORE/AFTER for every changed column, and (with --ui-label) records the
+         result in docs/runs/sgv_ui_diff_ledger.json. A label is CONFIRMED only when exactly ONE
+         non-technical column changed.
+"""
+import argparse
+import json
+import os
+import sys
+from datetime import date, datetime
+from decimal import Decimal
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "agent" / "src"))
+SNAP_DIR = ROOT / "docs" / "runs" / "snapshots"
+LEDGER = ROOT / "docs" / "runs" / "sgv_ui_diff_ledger.json"
+# Columns the ERP rewrites by itself on every save; ignored ONLY because they are clearly automatic.
+TECHNICAL = {"ULTIMA_ALTERACAO", "DATA_ALTERACAO", "DATA_ULTIMA_ALTERACAO", "USUARIO_ALTERACAO"}
+
+
+def norm(v):
+    if isinstance(v, (bytes, bytearray)):
+        import hashlib
+        return "blob:" + hashlib.sha256(bytes(v)).hexdigest()[:16]
+    if isinstance(v, (datetime, date)):
+        return v.isoformat()
+    if isinstance(v, Decimal):
+        return str(v)
+    return v.strip() if isinstance(v, str) else v
+
+
+def read_row(env, code):
+    from gti_fiscal_agent.firebird_reader import _connect  # read-only isolation
+    conn = _connect(env)
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT * FROM C000025 WHERE CODIGO = ?", (code,))
+        row = cur.fetchone()
+        if row is None:
+            raise SystemExit(f"product {code} not found")
+        names = [c[0].strip() for c in cur.description]
+        blob = {}
+        return {n: norm(v) for n, v in zip(names, row)}
+    finally:
+        conn.close()
+
+
+def compute_diff(before, after):
+    out = []
+    for f in sorted(set(before) | set(after)):
+        if before.get(f) != after.get(f):
+            out.append({"FIELD": f, "BEFORE": before.get(f), "AFTER": after.get(f), "technical": f in TECHNICAL})
+    return out
+
+
+def load_env():
+    for line in (ROOT / ".env").read_text(encoding="utf-8").splitlines():
+        if "=" in line and not line.startswith("#"):
+            k, _, v = line.partition("="); os.environ.setdefault(k.strip(), v.strip())
+
+
+def record(label, code, changes):
+    real = [c for c in changes if not c["technical"]]
+    ledger = json.loads(LEDGER.read_text(encoding="utf-8")) if LEDGER.exists() else []
+    entry = {"ui_label": label, "product": code, "recorded": datetime.now().isoformat(timespec="seconds"), "changed_columns": [c["FIELD"] for c in real],
+             "before": {c["FIELD"]: c["BEFORE"] for c in real}, "after": {c["FIELD"]: c["AFTER"] for c in real},
+             "confirmed": len(real) == 1, "note": "" if len(real) == 1 else ("no column changed" if not real else "more than one column changed; repeat changing a single field")}
+    ledger.append(entry)
+    LEDGER.write_text(json.dumps(ledger, ensure_ascii=False, indent=1), encoding="utf-8")
+    return entry
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("action", choices=["before", "diff"]); ap.add_argument("codigo"); ap.add_argument("--ui-label")
+    a = ap.parse_args(argv)
+    load_env()
+    SNAP_DIR.mkdir(parents=True, exist_ok=True)
+    path = SNAP_DIR / f"{a.codigo}_before.json"
+    if a.action == "before":
+        path.write_text(json.dumps(read_row(os.environ, a.codigo), ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+        print(f"snapshot saved: {path}"); return
+    if not path.exists():
+        raise SystemExit("run 'before' first")
+    changes = compute_diff(json.loads(path.read_text(encoding="utf-8")), read_row(os.environ, a.codigo))
+    print(f"{'FIELD':<28}{'BEFORE':<28}AFTER")
+    for c in changes:
+        print(f"{c['FIELD']:<28}{str(c['BEFORE']):<28}{c['AFTER']}{'   (technical, ignored)' if c['technical'] else ''}")
+    if a.ui_label:
+        print(json.dumps(record(a.ui_label, a.codigo, changes), ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

fiscal/scripts/unified_coverage_e2e.py

@@ -0,0 +1,107 @@
+"""READ-ONLY end-to-end of the UNIFIED fiscal coverage over a real Firebird database (default: TESTESOFICIAIS.FDB).
+
+    python scripts/unified_coverage_e2e.py [--db TESTESOFICIAIS] [--out docs/runs/unified_coverage_e2e.json]
+
+Reads the products with the Agent's own reader (SELECT only), classifies them through the Hub, then computes the operational states
+BEFORE (decision only) and AFTER (decision + PIS/COFINS + RTC when enabled). The ERP's RTC switch is reported as found; a what-if run
+with RTC forced ON / OFF uses the pure evaluator only (nothing is written, PARAMETROS is never touched).
+"""
+import argparse
+import json
+import os
+import sys
+from collections import Counter
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT)); sys.path.insert(0, str(ROOT / "scripts")); sys.path.insert(0, str(ROOT / "agent" / "src"))
+from dotenv import load_dotenv  # noqa: E402
+
+load_dotenv(ROOT / ".env")
+import local_completion as lc  # noqa: E402
+from central.app.operational_state import classify_product_state, summarize_operational_states  # noqa: E402
+from gti_fiscal_agent import firebird_reader, unified_fiscal  # noqa: E402
+from gti_fiscal_agent.client import HubClient  # noqa: E402
+from gti_fiscal_agent.runner import to_hub_product  # noqa: E402
+
+PIS_COLS = ("COD_ENTRADA_PIS", "COD_SAIDA_PIS", "ALIQ_PIS", "COD_ENTRADA_COFINS", "COD_SAIDA_COFINS", "ALIQ_COFINS")
+
+
+def old_unknown(product):
+    """The previous model's UNKNOWN_APPLICABILITY: no product-level evidence of PIS/COFINS at all."""
+    text = lambda v: "" if v is None else str(v).strip()  # noqa: E731
+    evidence = any(text(product.get(c)) for c in PIS_COLS) or text(product.get("PISCOFINS")).upper() == "S" or text(product.get("INCIDENCIA_PISCOFINS")).upper() not in ("", "NENHUMA")
+    return not evidence
+
+
+def resolved_crt(name, path):
+    """Company regime exactly as the Agent resolves it (deterministic company-context resolver)."""
+    from gti_fiscal_agent import company_context as cc
+    conn = lc.connect(path)
+    try:
+        cur = conn.cursor()
+        result = cc.resolve(cc.collect_evidence(cur), cc.config_from_env(lc._cfg_env(name)))
+        return result.get("company_crt") if result.get("status") == "PASS" else None
+    finally:
+        conn.close()
+
+
+def main():
+    ap = argparse.ArgumentParser(); ap.add_argument("--db", default="TESTESOFICIAIS"); ap.add_argument("--out", default="docs/runs/unified_coverage_e2e.json"); ap.add_argument("--crt", default=None); ap.add_argument("--fiscal-only", action="store_true", help="skip the Hub classification (decisions = EXACT_NCM); measures only the PIS/COFINS + RTC contribution")
+    a = ap.parse_args()
+    path = lc.allowlist()[a.db]; env = lc.env_for(path)
+    products = firebird_reader.read_products(env)
+    connection = firebird_reader._connect(env)                                        # READ COMMITTED READ ONLY (Agent reader)
+    try:
+        cursor = connection.cursor()
+        schema, _catalog, extras = unified_fiscal.load_rtc_context(cursor)
+        fiscal_products = unified_fiscal.read_products(cursor, schema)
+        cursor.execute("SELECT DISTINCT TRIM(CRT) FROM C000004"); crts = [r[0] for r in cursor.fetchall()]
+    finally:
+        connection.close()
+    crt = a.crt or resolved_crt(a.db, path) or (crts[0] if len(crts) == 1 else None)
+    client = HubClient(os.environ.get("HUB_URL", lc.HUB), os.environ["AGENT_DEV_TOKEN"])
+    decisions = [{"status": "EXACT_NCM"} for _ in products] if a.fiscal_only else client.classify_batch([to_hub_product(p) for p in products])
+    before_states = [classify_product_state(p, d) for p, d in zip(products, decisions)]
+    before = summarize_operational_states(before_states)
+    company = {"crt": crt}
+    runs = {}
+    for label, override in (("ERP_AS_FOUND", None), ("RTC_OFF_SIMULATION", False), ("RTC_ON_SIMULATION", True)):
+        conn = firebird_reader._connect(env)
+        try:
+            out = unified_fiscal.assess_from_connection(conn, company, rtc_override=override)
+        finally:
+            conn.close()
+        findings = out["findings"]
+        states = [classify_product_state(p, d, fiscal=findings.get(str(p["CODIGO"]))) for p, d in zip(products, decisions)]
+        summary = summarize_operational_states(states)
+        by_type, by_category = Counter(), Counter()
+        for f in findings.values():
+            for kind in {(b["type"], b["category"]) for b in f["blockers"]}:
+                by_type[kind[0]] += 1; by_category[kind[1]] += 1
+        changed = [{"product": s["product_code"], "BEFORE_STATUS": b["state"], "AFTER_STATUS": s["state"], "REASON": sorted({x["type"] for x in s["fiscal_blockers"]}) or ("NEEDS_REVIEW" if s["state"] == "NEEDS_REVIEW" else "")}
+                   for b, s in zip(before_states, states) if b["state"] != s["state"]]
+        total = summary["TOTAL_PRODUCTS"]
+        runs[label] = {"rtc_enabled": out["context"]["rtc_enabled"], "TOTAL_PRODUCTS": total, "COMPLETE_PRODUCTS": summary["COMPLETE_PRODUCTS"], "SAFE_BLOCKED_PRODUCTS": summary["SAFE_BLOCKED"],
+                       "FAILED_PRODUCTS": summary["FAILED_TECHNICAL"], "UNCLASSIFIED_PRODUCTS": summary["UNCLASSIFIED"],
+                       "COVERAGE_PERCENT": round(100 * summary["COMPLETE_PRODUCTS"] / total, 2) if total else 0.0,
+                       "INVARIANT_PASS": total == summary["COMPLETE_PRODUCTS"] + summary["SAFE_BLOCKED"] + summary["FAILED_TECHNICAL"] + summary["UNCLASSIFIED"],
+                       "PIS_BLOCKERS": by_category["PIS"], "COFINS_BLOCKERS": by_category["COFINS"], "RTC_BLOCKERS": by_category["RTC"], "OTHER_BLOCKERS": by_category["OTHER"], "blockers_by_type": dict(sorted(by_type.items())),
+                       "applicability": dict(Counter(f["applicability"]["PIS_COFINS"] for f in findings.values())), "rtc_applicability": dict(Counter(f["applicability"]["RTC"] for f in findings.values())),
+                       "changed_products": len(changed), "examples": changed[:30], "non_canonical_warnings": out["context"]["non_canonical_warnings"]["products"]}
+        if label == "ERP_AS_FOUND":
+            runs[label]["context"] = {k: v for k, v in out["context"].items() if k not in ("capabilities",)}
+    total = before["TOTAL_PRODUCTS"]
+    report = {"mode": "FISCAL_ONLY (no Hub decision)" if a.fiscal_only else "FULL (Hub decision + fiscal)", "database": a.db, "crt": crt, "products": len(products), "fiscal_products_read": len(fiscal_products),
+              "BEFORE": {"COMPLETE_PRODUCTS": before["COMPLETE_PRODUCTS"], "SAFE_BLOCKED_PRODUCTS": before["SAFE_BLOCKED"], "COVERAGE_PERCENT": round(100 * before["COMPLETE_PRODUCTS"] / total, 2),
+                         "UNKNOWN_APPLICABILITY_previous_model": sum(1 for p in fiscal_products if old_unknown(p))}, "runs": runs,
+              "SAFETY": {"FIREBIRD_WRITES": 0, "WRITE_ATTEMPTS": 0, "WRITE_SUCCESSES": 0, "connection_mode": "READ COMMITTED READ ONLY (Agent reader); no write-capable connection opened"}}
+    Path(ROOT / a.out).write_text(json.dumps(report, ensure_ascii=False, indent=1, default=str), encoding="utf-8")
+    print(json.dumps({k: report[k] for k in ("database", "crt", "products", "BEFORE")}, ensure_ascii=False))
+    for label, r in runs.items():
+        print(label, {k: r[k] for k in ("rtc_enabled", "TOTAL_PRODUCTS", "COMPLETE_PRODUCTS", "SAFE_BLOCKED_PRODUCTS", "FAILED_PRODUCTS", "UNCLASSIFIED_PRODUCTS", "COVERAGE_PERCENT", "INVARIANT_PASS", "PIS_BLOCKERS", "COFINS_BLOCKERS", "RTC_BLOCKERS", "OTHER_BLOCKERS", "non_canonical_warnings")})
+        print("   applicability", r["applicability"], "blockers", r["blockers_by_type"])
+
+
+if __name__ == "__main__":
+    main()