# 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..0020 (head `0020_not_null_timestamps`, 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.