GTI_GERENCIADOR_FISCAL/fiscal/docs/RELEASE_CANDIDATE_V1.md

GTI Fiscal 1.0.0-rc1 — Release Candidate

Status: COMPLETE_LOCAL_RC. Nothing was installed on a real client host and no real client database received a write (FIREBIRD_WRITES=0, FISCAL_MODE=DRY_RUN).

Architecture

Hub central (Docker: Hub + PostgreSQL)
        ^   HTTPS
Agent Windows (service GTIFiscalAgent)
        |   local, read-only
SGV Firebird (C000025 / C000004)

The Hub never accesses Firebird and never stores Firebird credentials or paths.

Frozen versions (release/RELEASE_MANIFEST.json)

item	value
GTI_FISCAL_VERSION (Hub, Agent, packages)	1.0.0-rc1 (release/VERSION, central/app/version.py, GET /version)
fiscal engine (ENGINE_VERSION) / decision (DECISION_VERSION)	0.3.0 / mission-04c-ipi-ex-split (unchanged: no fiscal semantics touched)
decision engines	fiscal-decision-v1, product-defaults-v1, icms-context-v1
migrations	0001..0022 (head 0022_agent_releases_enrollment, applied in production 2026-09-23; a fresh database is initialized by alembic upgrade head alone)
datasets	13 ACTIVE kinds with sha256/record_count in the manifest

What RC1 adds (no fiscal rule changes)

• Agent config: FISCAL_MODE (DRY_RUN | AUTO_APPLY), COMPANY_CODE, COMPANY_CNPJ, COMPANY_CRT_SOURCE (AUTO | EMISSOR | C000004), COMPANY_UF as an explicit, non-substituting override; AGENT_VERSION default 1.0.0-rc1.
• Single preflight (agent/scripts/preflight.py, enforced at service start): Hub reachability/auth/version, Firebird version + ODS, C000004/C000025, capabilities (NCM, IPI, CEST), company context (UF/CRT), schema/type guards, SQLite, log directory, mode/write consistency -> PREFLIGHT=PASS|FAIL + blockers.
• Technical zero-write in DRY_RUN: effective writes are FIREBIRD_WRITES=1 AND FISCAL_MODE=AUTO_APPLY; open_write_connection refuses otherwise; tests cover it (agent/tests/test_preflight_and_dry_run.py); scripts/prove_zero_write.py proves it on a database.
• REPROCESS_ALL result now carries the coverage report (NCM/IPI/CEST/CFOP/CSOSN/ST/role/company context) computed on the Agent from Hub decisions (gti_fiscal_agent/coverage.py, shared with the multi-database tooling).
• Windows package (deploy/agent-windows, scripts/build_agent_package.py): install / configure / preflight / start / stop / restart / status / uninstall; no secrets inside; secret-scanned zip with SHA-256 manifest.
• Hub production package (deploy/hub): compose with PostgreSQL on an internal network (no published port), persistent volume, healthchecks, restart policy, log rotation, required secrets, backup.sh, restore.sh, dataset seed export/import; APP_ENV=production refuses AGENT_DEV_TOKEN.
• Pilot profile pilot-construcao.env.example; planned (not installed) profiles/mmmodas|rincao|uniao.env.example with COMPANY_CRT_SOURCE=EMISSOR.

Profiles

client	company context	required config
CONSTRUCAO (first pilot)	company 000001, UF BA, CRT 1, AUTO_RESOLVED, HIGH	COMPANY_CODE=000001, COMPANY_CRT_SOURCE=AUTO; host preflight must confirm UF=BA / CRT=1
MMMODAS	CRT conflict (EMISSOR 1 / C000004 2)	COMPANY_CRT_SOURCE=EMISSOR required
RINCAO	company resolved via EMISSOR CNPJ (3 C000004 rows); CRT conflict (EMISSOR 3 / C000004 1)	COMPANY_CODE=000001, COMPANY_CRT_SOURCE=EMISSOR required
UNIAO	CRT conflict (EMISSOR 1 / C000004 3)	COMPANY_CRT_SOURCE=EMISSOR required

Follow-ups (explicitly not in RC1)

• dataset_versions() (~11 queries per classification request) can be memoized/cached; it dominates the ~15 ms cache-hit latency.
• Auto-apply stays disabled everywhere; enabling it for any real client needs the two pilot authorization layers and a separate decision.
• No dashboard, no Kubernetes/Redis/RabbitMQ.

External requirements for the first real pilot

1. Hub URL (or the Proxmox host / VM to deploy it on) and shell access to deploy deploy/hub, plus the public HTTPS name and the reverse proxy/TLS certificate.
2. The Windows host of the CONSTRUCAO client (remote access + administrator rights).
3. The real path of the client's SGV .FDB on that host (not the local copy's path).
4. A read-only Firebird account (user/password) entered locally on that host.
5. Explicit authorization to install the Windows Service GTIFiscalAgent there.
6. An Agent token generated with register_agent.py on the production Hub.