GTI_GERENCIADOR_FISCAL/fiscal/docs/superpowers/specs/2026-09-16-firebird-mission-00-design.md

Mission 00: Firebird Connectivity and Discovery

Goal

Use the Firebird installation associated with the locally installed ERP as read-only evidence to connect only to the authorized copy D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB, perform complete schema discovery, and document confirmed findings without implementing fiscal writes, image writes, services, or schedulers.

Scope and boundaries

• Files outside D:\PROJETOS\GTISISTEMAS\Projeto are read-only.
• Only TESTESOFICIAIS.FDB may be opened or queried.
• Other database files may be listed but must not be connected to, copied, or processed.
• No DML, DDL, procedure execution, generator changes, metadata changes, permission changes, or service lifecycle changes are allowed.
• Credentials and secrets found in ERP configuration are evidence of location only and must never enter source, reports, logs, or commits.

Connection strategy

Use the installed Firebird server and its compatible Python driver/client as the primary path. First inspect services, processes, executable and DLL versions, tools, and ERP configuration. Select the client only after its version and architecture are evidenced. Use an embedded/local client only as a documented fallback if the server path is unavailable and compatibility is proven. Do not install an arbitrary Firebird version.

The connection layer will enforce the absolute authorized database path and require database-level or transaction/driver-level read-only enforcement. The first database operation will be a minimal identity query. The sanitized connection description will include driver, client, architecture, host/port form, and target path, but no secrets.

Discovery flow

1. Detect Firebird capabilities and execute only safe catalog SELECT queries.
2. Collect engine version, dialect, ODS, charset, page size, database identity, relation counts, fields, keys, indexes, dependencies, generators, triggers, procedures, parameters, and compatible monitoring metadata.
3. Identify product candidates using names, fields, keys, indexes, counts, relationships, types, and minimal masked scalar samples.
4. Map product, stock, fiscal, company/branch, image/file, audit, and incremental concepts. Mark every mapping CONFIRMED, INFERRED, or UNKNOWN based on direct evidence.
5. Inspect trigger and routine source only as metadata text, without invoking routines or collecting source/blob contents that are sensitive or unnecessary.
6. Build fingerprint V1 from engine context, product structure, fiscal fields, relationships, image structure, and critical triggers.

Safety and sanitization

The existing read-only SQL boundary remains mandatory. Catalog capability failures are recorded as unavailable or query errors rather than treated as negative findings. Samples are small, scalar, masked, and purpose-limited. Raw BLOBs, credentials, customer data, and unnecessary commercial data are excluded. A path guard prevents accidental access to the ERP's original database even if configuration reveals it.

Project changes and verification

Changes are limited to the authorized project directory: path guard/driver integration, discovery tests and fixtures, fingerprint support, and the three current-state documents plus sanitized mission evidence. The .FDB remains ignored by Git. Verification includes focused safety/parser tests, full python -m pytest tests -q, git diff --check, sensitive-data review, and Git status/identity inspection. A single mission commit is created only when Git identity is already configured; otherwise report GIT_IDENTITY_NOT_CONFIGURED.

Outcomes

MISSION_00_COMPLETE requires real connection, confirmed engine details, evidence-backed product and fiscal mapping, image/incremental/trigger review, fingerprint V1, green tests, zero application writes, and no external file modification. Any unresolved connectivity or compatibility blocker produces MISSION_00_BLOCKED with the evidence and remaining gaps documented.

Explicit non-goals

Do not implement fiscal rules, APIs, image storage, product UPDATEs, Windows services, production schedulers, migrations, triggers, or database changes.